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IBM VA/SP: 


CMS User's Guide 


This publication is intended for the 
general CMS user. It contains information 
describing the interactive facilities of 
CMS, and includes examples showing you how 
to use CMS. 


"Part 1. Understanding CMS" contains 
sections that describe, in general terms, 
the CMS facilities andthe CMS and CP 


commands that you can use to control your 
virtual machine. If you are an experienced 
programmer who has used interactive 
terminal systems before, you may be able to 
refer directly to the VM/SP CMS Command and 


Macro Reference publication to find 
specific details about CMS commands that 
are summarized in this part. Otherwise, 


you may need to refer to later sections of 


this publication to gain a broader 

background in using CMS. The topics 

discussed in Part 1 are: 

e What It Means To Have acCMS Virtual 
Machine 

e VM/SP-CMS Environments and Mode 


Switching 
e What You Can Do with VM/SP-CMS Commands 
e The CMS File Systen 
e The Editors 
e Introduction to the CMS EXEC Processors 


e Using Real Printers, Punches, 


and Tapes 


Readers, 


"Part 2. Program Development Using CMS" 
is primarily for applications programmers 
who want to use CMS to develop and test OS 
and DOS programs under CMS. The topics 
discussed in Part 2 are: 


e Developing OS Programs Under CMS 
e Developing DOS Programs Under CMS 


e Using Access Method Services and VSAM 


Under CMS and CMS/DOS 


e How VM/SP Can 
Programs 


Help You Debug Your 


e Using the CMS Batch Facility 


e Programming for the CMS Environment 


Preface 


"Part 3. Learning To Use CMS EXECS" 
gives detailed information on creating EXEC 


procedures to use with CMS. The _ topics 
discussed in Part 3 are: 
e Building CMS EXEC Procedures 
e Using CMS EXECS with CMS Commands 
e Refining Your CMS EXEC Procedures 
e Writing CMS Edit Macros 
"Part 4. The HELP Facility" contains 
descriptions and examples of the use of 


HELP facility format words in creating HELP 
description files. 


Using the HELP Facility 

How the HELP Facility Works 
Tailoring the HELP Facility 
HELP File Naming Conventions 
Creating HELP Files 


Commands" 
in the CMS 


“Appendix A: Summary of CMS 
lists the commands available 
command environment. 


"Appendix B: Summary of CP Commands" 
lists the CP command privilege classes and 
Summarizes the commands available in the CP 
command environment. 


“Appendix Cs: Considerations for 3270 
Display Terminal Users" discusses aspects 
of VM/SP and CMS that are different or 


unique when you use a 3270 display 
terminal. 
“Appendix D: Sample Terminal Sessions" 


shows sample terminal sessions for: 


e Using the CMS Editor and CMS file systen 
commands 


e Using line-nunber the CMS 


editor 


editing with 


e Creating, assembling, 
OS program in CMS 


and executing an 
e Creating, assembling, and executing a 
DOS program in CMS/DOS 


e Using access method services in CMS 
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Terminology 


Some of the following terms are used, for 
convenience, throughout this publication: 


e The term “CMS/DOS" refers to the 
functions of CMS that become available 
when you issue the command 

set dos on 
CMS/DOS is a part of the normal CMS 
system, and is not a separate systen. 

Users who do not use CMS/DOS are 

sometimes referred to as OS users, since 


they use the OS’ simulation functions of 
CMS. 


e The term "CMS files" refers exclusively 
to files that are in the fixed biock 
format used by CMS file system commands. 
VSAM and OS data sets and DOS files are 
not compatible with the CMS file format, 
and cannot be manipulated using CMS file 
system commands. The terms "disk" and 
“"yirtual disk" are used interchangeably 
to indicate disks that are in your CMS 
virtual machine configuration. Where 
necessary, a distinction is made between 
CMS-formatted disks and disks in OS or 
DOS format. 


e "3270" refers to a series of display 
devices, namely, the IBM 3275, 3276 
Controller Display Station, and 3277, 


3278, and 3279 Display Stations. A 
specific device type is used only when a 
distinction is required between device 
types. 


Information about display terminal usage 
also applies to the IBM 3138, 3148, and 
3158 Display Consoles when used in display 
mode, unless otherwise noted. 


Any information pertaining to the IBM 
3284 or 3286 Printer also pertains’ to the 
IBM 3287, 3288, and 3289 printers, unless 
otherwise noted. 


e 3330" 
storage 


refers to the IBM 3330 Disk 
Models 1, 2, and 11, the IBM 
3333 Disk Storage and Control Models 1 
and 11, and the IBM 3350 Direct Access 
Storage in 3330 compatibility mode. 


e 2305" refers to the IBM 2305 Fixed Head 
Storage, Models 1 and 2. 


e "3340" refers to the IBM 3340 Direct 
Access Storage Facility and the IBM 3344 
Direct Access Storage. 


e 3350" refers to the IBM 3350 Direct 


Access Storage device when used in 
native mode. 
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e Any information pertaining to the IBM 
2741 terminal also applies to the IBM 
3767 terminal, unless otherwise noted. 


© 370x refers to the 3704/3705 
Communications Controllers. 

e "3370" refers to the IBM 3370 Direct 
Access Storage Device. 

e 3310" refers to the IBM 3310 Direct 


Access Storage Device. 


e "FB-512" refers to the IBM 3370 and 3310 
Direct Access Storage Devices. 


For a glossary of VM/SP terms, see the 


IBM Virtual Machine/System Product: Library 
Guide and Master Index, GC19-6207. 


SCRIPT/VS is aocomponent of the IBM 
Document Composition Facility progran 
product, which is available from IBM for a 
license fee. For additional information on 
SCRIPT/VS usage, see Document Composition 
Facility: User's Guide, SH20-9161. 
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bee 


Introduction, GC18-6200 


Terminal User's Guide, GC19-6206 


COREQUISITE PUBLICATIONS 


IBM Virtual Machine/System Product: 


eas Command and Macro Reference, 
C19-6209 

CP Command Reference for General Users, 

SC 19-6211 


System Messages and Codes, SC19-6204 
EXEC 2 Reference, SC24-5219 


System Product Editor 
SC24-5220 


User's Guide, 


System Product Editor 
Reference, SC24-5221 


Operating Systems in a Virtual Machine, 


GC 19-6212 


Command and Macro 


Sd 


RELATED VM/SP PUBLICATIONS 


Additional descriptions of various CHS 
functions and commands that are normally 
used by system support personnel are 
described in the following publications: 


IBM Virtual Machine/System Product: 


System Programmer's Guide, SC19-6203 


Qperator's Guide, SC19-6202 


Planning and System Generation Guide, 

SC 19-6201 

Information describing the CMS command 
CPEREP, a command used to generate output 
reports from VM/SP's error recording 
records, is contained in the IBM Virtual 


Machine/System Product OLTSEP and Error 
Recording Guide, SC19-6205 


Details on the use of OS/VS_ EREP 
operands, required to make use of CPEREP, 
are contained in the OS/VS, DOS/VSE, VMN/370 
Environmental Recording, Editing, and 
Printing Program, GC28-0772. 

There are three publications available 
as ready reference material when you use 
VM/SP and CMS. They are: 


IBM Virtual Machine Facility/370: 


Quick Guide for Users, Sx20-4400 


Commands (General User), SX20-4401 


Commands (Qther than General User), 

SX¥20-4402 

For information on OS/VS tape label 
processing, discussed with "Label 
Processing in OS Simulation" in this 


publication, refer to: 


OS/VS1 Data Management Services Guide, 


GC 26-3874 
OS/VS2 Data Management Services Guide, 
GC26-3875 
OS/VS Tape Labels, GC26-3795 
IPCS CMS commands are described in IBM 


WM/370 Interactive Problem Control Systen 
(IPCS) User's Guide, GC20-1823, and not in 
this publication. 


RELATED PUBLICATIONS FOR VSAM AND ACCESS 
METHOD SERVICES USERS 


CMS support of access method services is 
based on VSE/AF and VSE/VSAM. The control 
statements that you can use are described 
in Using VSE/VSAM Command and Macros, 
SC24-5144, 


Error messages produced by the access 
method services program, and return codes 
and reason codes, are listed in VSE/VSAM 
Messages and Codes, SC24-5146. 


For a detailed description of VSE/VSAM 
macros and macro parameters, refer to the 
VSE/AF Macro User's Guide, SC24-5210 

For information on OS/VS VSAM macros, 
refer to OS/VS Virtual Storage Access 
Method (VS AM) Programmer's Guide, 
GC26-3818. 


RELATED PUBLICATIONS FOR CMS/DOS USERS 


The CMS ESERV command invokes the VSE/AF 
ESERV program, and uses, aS input, the 
control statements that you would use in 
VSE/AF. These control statements are 
described in Guide to the DOS/VSE 
Assembler, GC33-4024. 


statements, used 
linkage editor under 
described in VSE/AF Systen 


Linkage editor control 
when invoking the 
CMS/DOS, are 


Control Statements, SC33-4024. 


For information on DOS/VSE 
tape label processing, 
following publications: 


and CMS/DOS 
refer to the 


VSE/AF Tape Labels, SC24-5212 


VSE/AF Macro User's Guide, GC24-5211 
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Part 1. Understanding CMS 


Learning how to use CMS is not an end in itself: you have specific tasks 
to do, and you need to use the computer to perform them. CMS has been 
designed to make these tasks easier, but if you are unfamiliar with CMS, 
then the tasks may seem more difficult. The information contained in 
Part 1 of the VM/SP CMS User's Guide is organized to help you make the 
acquaintance of CMS quickly, so that it enhances, rather than impedes, 
the performance of your tasks. 


"Section 1. What It Means To Have a CMS Virtual Machine" introduces 
you to VM/SP and its conversational component, CMS. It should help you 
to get a picture of how you, at a terminal, use and interact with the 
systen. 


During a terminal séssion, commands and requests that you enter are 
processed by different parts of the system. How and when you can 
communicate with these different programs, is described in "Section 2. 
VM/SP Environments and Mode Switching." 


There are more than two hundred commands and subcommands comprising 
the VMN/SP language. There are some that you may never need to use; there 
are others that you will use over and over again. "Section 3. What You 
Can Do With VM/SP-CMS Commands" contains a sampling of commands in 
various functional areas, to give you a general idea of the’ kinds of 
things you can do, and the commands available to help you do then. 


Almost every CMS command that you enter results in some kind of 
activity with a direct access storage device (DASD), known in CMS simply 
as a disk, or minidisk. Data and programs are stored on disks in what 
are called "files." "Section 4. The CMS File System" introduces you to 
the creation and handling of CMS files. 


"Section 5. The Editors" contains all the basic information you need 
to create and write a disk file directly from your terminal, or to 
correct or modify an existing CMS file. 


Just as important as the CMS editors are the CMS facilities, called 
EXEC and EXEC 2 processor or interpreter. Using EXEC files, you can 
execute many commands and programs by entering a single command line 
from your terminal, or you can write your own CMS commands. "Section 6. 
Introduction to the EXEC Processors" presents a survey of the basic 
characteristics and functions of EXEC. 


"Section 7. Using Real Printers, Punches, Readers, and Tapes" 


discusses how to use punched cards and tapes in CMS, and how to use your 
virtual printer and punch to get real output. 
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Section 1. What It Means to Have a CMS Virtual Machine 


Virtual Machine/System Product (VM/SP) is a program product that 
controls "virtual machines." A virtual machine is the functional 
equivalent of a real computer that you control from your terminal, using 
a command language of active verbs and nouns. 


The command languages correspond to the components! of VM/SP. CP 
controls the resources of the real machine; that is, the physical 
machine in your computer room; it also manages the communications among 
virtual machines, and between a virtual machine and the real systen. 
CMS is the conversational operating system designed specifically to run 
under CP; it can simulate many of the functions of the OS and DOS 
operating systems, so that you can run many OS and DOS programs ina 
conversational environment. 


Although this publication is concerned primarily with using CMS, it 
also contains examples of CP commands that you, as a CMS user, should be 
familiar with. 


How You Communicate With VM/SP 


When you are running your virtual machine under VM/SP, each command, or 
request for work, that you enter on your terminal is processed as it is 
entered; usually, you enter one command at atime and commands are 
processed in the order that you enter then. 


You can enter CP commands from either the CP or CMS environments; but 
you cannot enter CMS commands while in the CP environment. The concept 
of "environments" in VM/SP is discussed in "Section 2. VM/SP 
Environments and Mode Switching." 


After you have typed or keyed in the line you wish to enter, you 
press the Return or Enter key on the keyboard. When you press this key, 
the line you have entered is passed to the command environment you want 
to have process it. If you press this key without entering any data, 
you have entered a "null line." Null lines sometimes have special 
meanings in VM/SP. 


If you make a mistake entering a command line, VM/SP tells you what 
your mistake was, and you must enter the line again. The examples in 
this publication assume that the command lines are correctly entered. 


You can enter commands using any combination of uppercase and 
lowercase characters; VM/SP translates your input to uppercase. 


Examples in this publication show all user-entered input lines in 
lowercase characters and system responses in uppercase characters. 
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The CP Command Lanquage 


You use CP commands to communicate with the control program. CP commands 
control the devices attached to your virtual machine and their 
characteristics. 


For example, if you want to allocate additional disk space for a work 
area or if you want to increase the virtual address space assigned to 
your virtual machine, use the CP command DEFINE. CP takes care of the 
Space allocation for you and then allows your virtual machine to use it. 


Or if, for example, you are receiving printed output at your terminal 
and do not want to be interrupted by messages from other VM/SP users, 
you can use the CP command SET MSG OFF to refuse messages, since it is 
CP that handles communication among virtual machines. 


Using CP commands, you can also send messages to the system operator 
and to other users, modify the configuration of devices in your virtual 
Machine, and use the virtual machine input/output devices. CP commands 
are available to all virtual machines using VM/SP. You can invoke these 
commands when you are in the virtual machine environment using CMS (or 
some other operating system) in your virtual machine. 


The CP commands and command privilege classes (not all commands are 
available to all users) are listed in "Appendix B: Summary of CP 
Commands". The CP Commands applicable to the average user are discussed 
in detail in the VM/SP CP Command Reference for General Users. The rest 
of the CP commands are discussed in VM/SP Operator's Guide. However, 
Since many CP commands are used with CMS commands, some of the CP 
commands you will use most frequently are discussed in this publication, 
in the context of their usefulness for a CMS application. To aid you in 
distinguishing between CMS commands and CP commands, all CP commands 
used in examples in this publication are prefaced with "Cp". 


The CMS Command Language 


The CMS command language allows you to create, modify, and debug problem 
or application programs and, in general, to manipulate data files. 


Many OS language processors can be executed under CMS: the assembler, 
VS BASIC, OS FORTRAN, VS FORTRAN, OS/VS COBOL, and OS PL/I Optimizing 
and Checkout Compilers. In addition, the DOS/VS COBOL, DOS PL/I, VS 
APL, and DOS VS RPG II Program Products are supported. You can find a 
comprehensive list of language processors that can be executed under CMS 
and relevant publications in the VM/SP Introduction. CMS executes the 
assembler and the compilers when you invoke them with CMS commands. The 
ASSEMBLE command is used to present examples in this publication; the 
supported compiler commands are described in the appropriate DOS and OS 
program product documentation. 


When you invoke the EDIT command, the System Product Editor places 
you in CMS (EDIT) compatibility mode. In this mode the CMS editor and 
the System Product Editor both allow you to create and modify files. 
The CMS EXEC interpreter and the EXEC 2 interpreter both provide 
execution procedures consisting of CP and CMS commands; they also 
provide the conditional execution capability of a macro language. The 
DEBUG command gives you several program debugging subcommands. 


Other CMS commands allow you to read cards from a virtual card 
reader, punch cards to a virtual card punch, and print records ona 
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virtual printer. Many commands are provided to help you manipulate your 
virtual disks and files. 


You use the HELP command to display at your terminal information on 
how to use CP commands and CMS commands, subcommands, and EXECs, and 
explanations of CP and CMS messages. You can issue the HELP command 
when a brief explanation of syntax, a parameter, or function is 
sufficient, thereby avoiding interrupting your terminal session to refer 
to a manual. 


Since you can invoke CP commands from within the CMS virtual machine 
environment, the CP and CMS command languages are, for practical 
purposes, a single, integrated command language for CMS users. 


GETTING COMMANDS INTO THE SYSTEM 


Before you can use CP and CMS, you should know (1) how to operate your 
terminal and (2) your userid (user identification) and password. 


The Terminal: Your Virtual Console 


There are many types of terminals you can use as a VMB/SP virtual 
console. Before you can conveniently use any of the commands and 
facilities described in this publication, you have to familiarize 
yourself with the terminal you are using. Generally, you can find 
information about the type of terminal you are using and how to use it 
with VM/SP in the VM/SP Terminal User's Guide. If your terminal isa 
3767, you also need the IBM 3767 Operator's Guide. 


In this publication, examples and usage notes assume that you are 
uSing a typewriter-style terminal (such as a 2741). If you are using a 
display terminal (such as a 3270), consult "Appendix C: Considerations 
for 3270 Display Terminal Users" for a discussion of special techniques 
that you can use to communicate with VM/SP. 


Your Userid and Password: Keys into the System 


Your userid is a symbol that identifies your virtual machine to VM/SP 
and allows you to gain access to the system. Your password is a symbol 
that functions aS a protective device ensuring that only those allowed 
can use your virtual machine. The userid and password are usually 
defined by the system programmer for your installation. 


Contacting VM/SP 


To establish contact with VM/SP, you switch the terminal device on and 
VM/SP responds with some form of the message 


VM/370 online 


to let you know that VM/SP is running and that you can use it. If you 
do not receive the "VM/370 online" message, see the VM/SP Terminal 
User's Guide for specific directions. You can now press the Attention 
key (or equivalent) on your terminal and issue the LOGON command to 
identify yourself to the system: 
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cp logon smith 
where SMITH represents a userid. The LOGON command is entered by 
pressing the Return (or Enter) key. If VM/SP accepts your userid, it 
responds by asking you for your password: 

ENTER PASSWORD: 


You then enter your password, the displaying of it may be supressed, 
depending on your terminal. 


LOADING CMS IN THE VIRTUAL MACHINE: THE IPL COMMAND 


You load CMS in your virtual machine using the IPL command: 

cp ipl cms 
where "cms" is assumed to be the saved systen NRame for your 
installation's CMS. You could also load CMS by referring to it using 
its virtual device address, such as 190: 

cp ipl 190 
VM/SP responds by displaying a message such as: 


VM/SP CMS - 02/28/79 12:02 


to indicate that the IPL command executed successfully and that CMS is 
loaded into your virtual machine. 


Your userid may be set up for an automatic IPL, so that you receive 
this message, indicating that you are in the CMS command environment, 
without having to issue the IPL command. 


Now you can enter a null line to begin your virtual machine 
operation. 


Note: If this is the first time you are using a new virtual disk 
assigned to you, you receive the message: 


DMSACC112S DISK"'A(191)* DEVICE ERROR 


and you must "format" the disk, that is, prepare it for use with CMS 
files. See "Formatting Virtual Disks" below. 


Logical Line Editing Symbols 


To aid you in entering command or data lines from your terminal, VM/SP 
provides a set of logical line editing symbols, which you can use to 
correct mistakes as you enter lines. Each symbol has been assigned a 
default character value. These normally are: 


Symbol Character 
Logical character delete a 
Logical line end _ # 
Logical liné delete g 
Logical escape " 
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Logical Character Delete 


The logical character delete symbol (@) allows you to delete one or nore 
of the previous characters entered. The @® deletes one character per @ 
entered, including the ¢ and # logical editing characters. For example: 


ABC#@a results in AB 
ABC@D results in ABD 
Z@DEF results in DEF 
ABC@a@@ deletes the entire string 


Logical Line End 


The logical line end symbol (#) allows you to key in more’ than one 
command on the same line, and thus pinimizes the amount of time you have 
to wait between entering commands. You type the # at the end of each 
logical command line, and follow it with the next logical command line. 
VM/SP stacks the commands and executes them in Sequence. For example, 
the entry: 


query blip#query rdymsg#query search 
is executed in the same way as the entries: 


query blip 
query rdymsg 
query search 


The logical line end symbol also has special significance for the #CP 
function. Beginning any physical line with #CP indicates that you are 
entering a command that is to be processed by CP immediately. If you 
have set a character other than # as your logical line end symbol, you 
should use that character instead of a #. 


Logical Line Delete 


The logical line delete symbol (¢) (or 9 for Teletype! Model 33/35 
terminals) deletes the entire previous physical line, or the last 
logical line back to (and including) the previous logical line end (#). 
You can use it to cancel a line containing many or serious errors. Ifa 
# immediately precedes the ¢ sign, only the # sign is deleted, since the 
# indicates the beginning of a new line, and the ¢ cancels the current 
line. For example: 


e Logical Line Delete: 


ABC#DEF¢ deletes the #DEF and results in ABC 
ABC#¢ results in ABC 
ABC#DEF¢#GHI results in ABC#GHI 
ABC#DEF¢GHI results in ABCGHI 
e Physical Line Delete: 
ABC¢ deletes the whole line 
Note that when you cancel a line by using the ¢ logical line delete 


1Trademark of the Teletype Corporation, Skokie, Illinois. 
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symbol, you do not need to press a carriage return; you can continue 
entering data on the sane line. 


Logical Escape 


The logical eScape symbol (") causes VM/SP to consider the next 
Character entered to be a data character, even if it is normally one of 
the logical line editing symbols (@, ¢, ", or #). For example: 


ABC"¢D results in ABC¢D 
NHABC™" results in “ABC® 


If you enter a single logical escape symbol (") as the last character 
on a line, or on a line by itself, it is ignored. 


When you enter logical escape characters in conjunction with other 
logical editing characters, the results may be difficult to predict. 
For example, the lines: 


ABC"™"@DEF 
ABC""@@DEF both result in the line: ABCDEF 


Defining Logical Line Editing Symbols 


The logical line editing symbols are defined for each virtual machine 
during VM/SP system generation. If your terminal's keyboard lacks any 
of these special characters, your installation can define other special 
characters for logical line editing. You can find out what logical line 
editing symbols are in effect for your virtual machine by entering the 
command: 

cp guery terminal 
The response might be something like: 

LINEND # , LINEDEL ¢ , CHARDEL @ , ESCAPE " 

LINESIZE 130, MASK OFF, APL OFF, ATTN OFF, MODE VS 


You can use the CP TERMINAL command to change the logical line 
editing characters for your virtual machine. For example, if you enter: 
cp terminal linend / 
Then, the line: 
input # line / input / # 
would be interpreted: 
input # line 
input 
$ 
The terminal characteristics listed in the response to the CP QUERY 


TERMINAL command are all controlled by operands of the CP TERAINAL 
command. 
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HOW VM/SP RESPONDS TO YOUR COMMANDS 


CP and CMS respond differently to different types of requests. All CMS 
command responses (and all responses to CP commands that are entered 
from the CMS environment) are followed by the CMS ready message. fhe 
form of the ready message can vary, Since it can be changed using the 
SET command. The long form of the ready message is: 

R; T=7.36/19.89 09: 26:11 

If you have issued the command: 

set rdymsg smsg 
the ready message looks like: 

R; 

When you enter a command line incorrectly, you receive an error 
message, describing the error. The ready message contains the last 5 
digits (4 digits for a negative return code) from the command: for 
example; 

R (00028) ; 
indicates that the return code from the command was 28. 


A ready message from the command may contain a negative return code; 
for example: 


R(-0001) ; 


indicates that the return code from the command was -0001. 


Some Sample CP and CMS Command Responses 


If you enter a CP or CMS command that requests information about your 
virtual machine, the response should be the information requested. For 
example, if you issue the command: 


cp display g 


CP responds by showing you the contents of your virtual machine's 
general registers, for example: 


GPR O = 00000003 00003340 000007A0 00000003 
GPR 4 = 00000848 C44HO4040 00000040 00002DF0 
GPR 8 = 90000008 000132F8 00002BA0 00002230 
GPR 12 = 00003238 FFFFFFFD 50013386 00000000 


Sinilarly, if you issue the CMS command: 
listfile * assemble c 
you might receive the following information: 


JUNK ASSEMBLE C1 
MY PROG ASSEMBLE C1 


If you enter a CP command to alter your virtual machine configuration 
or the status of your spool files, CP responds by telling you that the 
task is accomplished. The response to: 
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cp purge reader all 
might be: 
0004 FILES PURGED 


Some CP commands, those that alter some of the characteristics of 
your virtual machine, give you no response at all. If you enter: 


cp spool e class x hold 
you receive no response from CP. 

Certain CMS commands may issue prompting messages, to reguest you to 
enter more information. The SORT command, which sorts CMS disk files, 
is an example. If you enter: 

sort in file a1 out file al 
you are prompted with the message: 


DMSSRT604R ENTER SORT FIELDS: 


and you can then specify which fields you wish the input records to be 
sorted on. 


Getting Acquainted With CMS 


If you have just logged on for the first time, and you want to try a few 
CMS commands, enter: 


query disk a 
the response might look like: 


| LABEL cuu M STAT CYL TYPE BLKSIZE FILES BLKS USED-(%) BLKS LEFT BLK TOTAL 
| MYDISK 191 A R/W 5 3330 1024 171 1221-92 107 1328 


The response should tell you that you have an A-disk at virtual address 
191; it also provides information such as how much room there is on the 
disk and how much of it is used. Again, if you receive an error message 
that indicates the disk may not be formatted, see "Formatting Virtual 
Disks." 


Your A-disk is the disk you use most often in CMS, to contain your 
CMS files. Files are collections of data, and may have many purposes. 


Note: When you issue the EDIT command, the System Product Editor 
automatically places you in CMS Editor (EDIT) compatibility mode. In 
this mode, you can issue both EDIT and XEDIT subcommands. For complete 
information on EDIT compatibility mode, as well as instructions on how 
to invoke the CMS editor itself, refer to the publication VM/SP System 
Product Editor Command and Macro Reference. 


For this exercise, the data is meaningless. Using the CMS Editor, 
enter; 


edit junk file 


You should receive the response: 


10 IBM VM/SP CMS User's Guide 


NEW FILE: 
EDIT: 


which indicates that this file does not already exist on your A-disk. 
Enter: 


input 
You should receive the response: 

INPUT: 
and you can start to create the file, that is, write input records that 
are eventually going to be written onto your A-disk. Enter 5 or 6 data 
lines, such as: 

hickory dickory dock 

the mouse ran up the clock 

the clock struck one 


and down he run 
dickory hickory dock 


Now, enter a null line (one with no data). You should receive the 
message: 


EDIT: 
Enter: 
file 
You should see the message: 
R; T=0.01/0.02 09:31:29 
You have just written a CMS file onto your A-disk. If you enter: 
type junk file a 
you should see the following: 
HICKORY DICKORY DOCK 
THE MOUSE RAN UP THE CLOCK 
THE CLOCK STRUCK ONE 
AND DOWN HE RUN 
DICKORY HICKORY DOCK 


The CMS command, TYPE, requested a display of the disk file JUNK 
FILE, on your A-disk. 


To erase the file, enter: 
erase junk file 
Now, if you reissue the TYPE command, you should receive the message: 
FILE NOT FOUND 
Most CMS commands create or reference disk files, and are as easy to 


use as the commands shown above. Your CMS disks are among the most 
important features in your VM/SP virtual machine. 
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Virtual Disks and How They Are Defined 


Under VMN/SP, a real direct access storage device (DASD) (disk pack) or 
an FB-512 device can be divided into many small areas, called minidisks. 
Minidisks (also called virtual disks because they are not equivalent to 
an entire real disk) are defined in the VM/SP directory, as extents on 
real disks. For CMS applications, you never have to be concerned with 
the extents oon your minidisks; when you use cCMS-formatted minidisks, 
they are, for practical purposes, functionally the same as real disks. 
Minidisks can also be formatted for use with OS or DOS data sets or VSAM 
files. 


You can have two types of disks, permanent and temporary. Permanent 
disks persist across logons while temporary disks are automatically 
destroyed at logoff. Both types may be attached to your machine during 
a terminal session. Permanent disks are defined in the VM/SP directory 
entry for your virtual machine. Temporary disks are those you define for 
your own virtual machine using the CP DEFINE command, or those attached 
to your virtual machine by the system operator. 


PERMANENT VIRTUAL DISKS 


The VMN/SP directory entry for your userid defines your permanent virtual 


disks. Each disk has associated with it an access mode specifying 
whether you can read and write on the disk or only read from it (its 
read/write status). Virtual disk entries in the VM/SP directory may 


look like the following: 


MDISK 190 2314 000 050 CMS190 
MDISK 191 3330 010 005 BDISKE 
MDISK 1948 3330 010 020 cCMSO001 
MDISK 195 FB-512 1000 500 FBDISK 
MDISK 198 3330 050 010 CMS192 
MDISK 19E 3330 010 050 CMS19E 


Dam a we 


The first two fields describe the device, minidisk in this example, 
and the virtual address of the device. Virtual addresses (shown above 
as 190, 191, and so on), are the names by which you and VM/SP identify 
the disk. Each device in your virtual machine has an address which may 
or may not correspond to the actual location of the device on the VM/SP 
systen. 


The third field specifies the device type of your virtual disk. For 
count-key-data devices, the fourth and fifth fields specify the starting 
real cylinder at which your virtual disk logically begins and the number 
of cylinders allocated to your virtual disk, respectively. For FB-512 
devices, the fourth field specifies the starting real block numbers 
where your virtual disk begins, andthe fifth field is the number of 
blocks allocated to your virtual disk. 


The sixth field is the label of the real disk on which the virtual 
disk is defined and the seventh field is a letter specifying the 
read/write mode of the disk; "R" indicates that the disk is a read-only 
disk, and "W" indicates that you have read/write privileges. The MDISK 
control statement of the Directory Service Program is described in the 
VM/SP Planning and System Generation Guide. 
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DEFINING TEMPORARY VIRTUAL DISKS 


Using the CP DEFINE command, you can attach a temporary disk to your 
virtual machine for the duration of a terminal session. The following 
command allocates a 10-cylinder temporary disk from a 3330 device and 
assigns it a virtual address of 291: 


cp define t3330 as 291 cyl 10 
When you define a minidisk, you can choose any valid address that is not 
already assigned to a device in your virtual machine. Valid addresses 


for minidisks range from 001 through 5FF, for a virtual machine in basic 
control node. 


FORMATTING VIRTUAL DISKS 


Before you can use any new virtual disk, you must format it. This 
applies to new disks that have been assigned to you and to temporary 
disks that you have allocated with the CP DEFINE command. When you 
issue the FORMAT command you must use the virtual address you have 
defined for the disk and assign a CMS mode letter, for example: 

format 291 c 
CMS then prompts you with the following message: 


DMSFOR603R FORMAT WILL ERASE ALL FILES ON DISK 'C(291)". DO YoU 
WISH TO CONTINUE? (YES|NO): 


You respond: 

yes 
CMS then asks you to assign a label for the disk, which may be anything 
you choose. Labels can have a maximum of 6 characters. When _ the 
message: 


DMSFOR605R ENTER DISK LABEL? 


is issued, you respond by supplying a disk label. For example, if this 
is a temporary disk, you might enter: 


scrtch 
CHS then erases all the files on that disk, if any existed, and formats 
the disk for your use. When you enter the label, CMS responds by 
telling you: 

FORMATTING DISK ‘'C* 

'10' CYLINDERS FORMATTED ON 'C(291)*. 

R; T=0.15/1.60 11:226:03 

The FORMAT command should only be used to format CMS disks, that is, 


disks you are going to use to contain CMS files. In addition, this 
command allows you a choice of physical disk block size as an option. 


| Refer to the VM/SP CMS Command and Macro Reference for details. Format 


disks for OS, DOS, or VSAM applications, using the Device Support 
Facilities. See VM/SP Operator's Guide for details. 


SRST eR TT NS TE SS ee 
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Sharing Virtual Disks: Linking 


Since only one user can own a virtual disk, and there are many occasions 
that require users to share data or programs, VM/SP allows you to share 
Virtual disks, on either a permanent or temporary basis, by "linking." 


Permanent links can be established for you in your VM/SP directory 
entry. These disks are then a part of your virtual machine 
configuration every time you log on. 


You can also have another user's disk temporarily added to your 
configuration by using the CP LINK command. For example, if you have a 
program that uses data that resides on a disk identified in userid 
DATA's configuration as a 194, and you know that the password assigned 
to this disk is GO, you could issue the conmand: 


cp link to data 194 as 198 r pass= go! 


DATA's 194 disk is then added to your virtual machine configuration at 
virtual address 198. 


The "R"™ in the command line indicates the access mode; in this case, 
it tells CP that you only want to read files from this disk and you will 
not be allowed to write on it. If you try to issue this command when 
someone already has write access to that disk, you will not be able to 
establish the link. If you want to link to DATA in any event, you can 
reissue the LINK command using the access mode RR: 


cp link data 194 198 rr go? 


The keywords 'TO"', ‘AS*", and "PASS=" are optional; you do not have to 
specify then. 


However, note that uSing the RR access allows one user to read a disk 
while another is updating the same disk at the same tine. This may 
produce unpredictable results. 


You can also use the CP LINK command to link to your own disks. For 
example, if you log on and discover that another user hasS access to one 
of your disks, you may be given read-only access, even if itis a 
read/write disk. You can request the other user to detach your disk 
from his virtual machine, and after he has done so, you can establish 
the link: 


cp link * 191 191 


When you link to your own disks, you can specify the userid as * and you 
do not need to specify the access mode or a password. 


You can find more information about the CP LINK command and CP access 
modes in VM/SP CP Command Reference for General Users. 


1Note that the password cannot be entered on the command line if the 
password suppression facility was specified at sysgen. 
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Identifying Your Disk To CMS: Accessing 


LINK and DEFINE are CP commands: they tell CP to add DASD devices to 
your virtual machine configuration. CMS must also know about these 
disks, and you must use the ACCESS command to establish a_ filemode 
letter for then: 

access 194 b 


CMS uses filemode letters to manage your files during a_ terminal 
session. By using the ACCESS command you can control: 


e Whether you can write on a disk or only read from it (its read/write 
status) 


e The library search order for programs executing in your virtual 
machine 


e Which disks are to contain the new files that you create 


If you want to know which disks you currently have access to, issue 
the command: 


query search 


You might see the following display: 


PER191 191 A R/W 
DAT194 198 B R/O 
CMS190 190 § R/O 
CMS19EF 19E Y R/O 


The first column indicates the label on the disk (assigned when the 
disk is formatted), and the second column shows the virtual address 
assigned to it. 


The third column contains the filemode letter. All letters of the 
alphabet are valid filemode letters. 


The fourth column indicates the read/write status of the disk. The 
190 and 19F disks in this example are read-only disks that contain the 
CMS nucleus and disk-resident commands for the CMS systen. You will 
probably use your 191 (A) disk aS your primary read/write work disk. 
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RELEASING VIRTUAL DISKS 


When you no longer need a disk during a terminal session, use the CMS 
command RELEASE: 


release c 
When you want to assign a currently active filemode letter to another 
disk, issue the ACCESS command to assign that filemode letter to another 
disk. It is not necessary to release an accessed disk prior to accessing 
another disk with the same filemode. 


When you no longer need disks in your virtual machine configuration, 
use the CP command DETACH to disconnect them from your virtual machine: 


cp detach 194 
cp detach 291 


If you are going to release and detach the disk at the same time, you 
can use the DET option of the RELEASE command: 


release 194 (det 


For more information on controlling disks in CMS, see "Section 4. The 
CMS File System." 
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Section 2. VM/SP Environments and Mode Switching 


When you are using VM/SP, your virtual machine can be in one of two 
possible "environments": the CP, or control program environment, or the 
virtual machine environment, which may be CMS. The CMS environment has 
several subenvironments, sometimes called "modes." Each environment or 
subenvironment accepts particular commands or subcommands, and each 
environment has its own entry and exit paths, responses and error 
messages. If you have a good understanding of how the VM/SP 
environments are related, you can learn to change environments quickly 
and use your virtual machine efficiently. 


This section introduces the CP and CMS environments that you use and 
describes: 


e Entry and exit paths 
e Command subsets that are valid as input 


Figure 2 summarizes the VM/SP command environments and lists’ the 
commands and terminal paths that allow you to go from one environment to 
another. 


Any "Class Any” CMS Subset 
CP Command 
LOGON Any CMS Subset Command 


Any CP Command 


HX 
Any CP Command? 


RETURN 
#CP Command Line 


CMS Environment CMS EDIT Environment 


Any CMS Command Any CMS EDIT 
IPL CMS Any CP Command Subcommand 
BEGIN? CMS EDIT fn ft FILE or QUIT 


EXTERNAL Any CMS EDIT Macro 
CMS 
INPUT 


#CP Command Line 


Execute any OS or 
CMS Program 

SET DOS ON 

DEBUG 

#CP Command Line 


INPUT MODE 


Any Input Line 
Carrier return or 


null line 
#CP Command Line 


DEBUG Environment 


Any DEBUG Subcommand 
RETURN or HX 
GO 
#CP Command Line 


CMS/DOS Environment 


Any CMS Command 

Any CMS/DOS Command 

Any CP Command 

Execute any DOS 
Program 

#CP Command Line 


Notes: 


4. The CP environment may be entered from any other environment either by 
using your terminal’s Attention key or equivalent, or by entering the 
command #CP. 

2. Any CP command that is valid for your privilege class. Any time a CP 
command can be entered, it may be prefixed by #CP. 

Program Execution 3. The BEGIN command returns your virtual machine to the environment it 
was in when CP was entered. For example: 

HX or (Abend) 

(Breakpoint) 


(Address Stop) 


e If you were in edit or input made, the current line pointer remains 
unchanged. 

e If you were executing a program, execution resumes as the instruction 
address indicated in the PSW. 


Figure 2. VM/SP Environments and Mode Switching 
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With the exception of input mode in the edit environment, you can 
always determine which environment your virtual machine is in by 
pressing the Return or Enter key on a null line. The responses you 
receive and the environments they indicate, are: 


Response Environment 

CP CP 

CMS CMS 

CMS (DOS ON) CMS/DOS 

EDIT: Edit 

CMS SUBSET CMS Subset 

DEBUG Debug 

XEDIT XEDIT, System Product Editor 


The CP Environment 


When you log on to VMS/SP, your virtual machine is in the CP environment. 
In this environment, you can enter any CP command that is valid for your 
privilege class. This publication assumes that you are a general, or 
Class G, user. You can find information about the commands that you can 
use in the VM/SP CP Command Reference for General Users. 


Only CP commands are valid terminal input in the CP environment. You 
can, however, preface a CP command line with the characters "CP" or 
"#CP", followed by one or more blanks, although it is not necessary. 
These functions are described under "The CMS Environment." 


You can enter CP commands from other VM/SP environments. There may 
be times during your terminal session when you want to enter the CP 
environment to issue one or more CP commands. You can do this from any 
other environment by doing either of two things: 

1. Issue the command: 
#cp 
2. Use your terminal's Attention key (or equivalent). On a 2741 
terminal, you must normally press the Attention key twice, quickly, 


to enter the CP environment. 


The following message indicates that your virtual machine is in the 
CP environment: 


CP 


After entering whatever CP commands you need to-use, you return your 
virtual machine to the environment or mode that it came from by using 
the CP command: 


cp begin 


which, literally, begins execution of your virtual machine. 


The CMS Environment 


You enter the CMS environment from CP by issuing the IPL command, which 
loads CMS into your virtual storage area. If you are planning to use 
CMS for your entire terminal session, you should not have to IPL again 
unless a program failure forces you into the CP environment. 
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When you issue the IPL command, specify the named system CMS at your 
installation. For example: 


cp ipl cms 


When your virtual machine is in the CMS environment, you can issue 
any CMS command and any of the CP commands that are valid for your user 
privilege class. You can also execute many of your own OS or DOS 
programs; the ways you can execute programs are discussed in "Section 8. 
Developing OS Programs Under CMS" and "Section 9. Developing DOS 
Programs Under CMs." 


You can enter CP commands from CMS in any of the following ways: 


e Using the implied CP function of CMS (See Note.) 
e With the CP command 
e With the #CP function 


Note: For the most part, you may enter any CP command directly from the 
CMS environment. This implied CP function is controlled by an operand 
of the CMS SET command, IMPCP. You can determine whether the implied CP 
function is in effect for your virtual machine by entering the command: 


query impcp 

If the response is; 
IMPCP = OFF 

you can change it by entering: 
set impcp on 


When the implied CP function is set off, you must use either the CP 
command or the #CP function to enter CP commands from the CMS 
environment. CP commands that you execute in EXEC procedures must 
always be prefaced by the CP command, regardless of the implied CP 
setting. An example of using the CP command is: 


cp close punch 


When you issue CP commands from the CMS environment either implicitly 
or with the CP command, you receive, in addition to the CP response (if 
any), the CMS ready message. If you use the #CP function, discussed 
next, you do not receive the ready message. 


You can preface any CP command line with the characters "&cCP", 
followed by one or more blanks. When you enter a CP command this way, 
the command is processed by CP immediately; it is as if your virtual 
machine were actually in the CP environment. 


EDIT, INPUT, AND CMS SUBSET 


The CMS editor is a VM/SP facility that allows you to create and modify 
data files that reside on CMS disks. The editor environment, more 
commonly called the edit environment, is entered when you issue the CMS 
command EDIT, specifying the identification of a data file you want to 
create or modify. 


Note: When you issue the EDIT command, the System Product Editor 


automatically places you in CMS Editor (EDIT) compatibility mode. In 
this mode, you can issue both EDIT and XEDIT subcommands. For complete 
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information on EDIT compatibility mode, as well as instructions on how 
to invoke the System Product Editor, refer to the publication VM/SP 
System Product Editor Command and Macro Reference. 


edit myfile assemble 
is an example of how you would enter the edit environment to either 


create a file called MYFILE ASSEMBLE or to make changes toa disk file 
that already exists under that name. 


When you enter the edit environment your virtual machine is 
automatically in edit mode, where you can only issue EDIT or XEDIT 
subcommands or CP commands prefaced by "#CP." EDIT subcommands tell the 


editor what you wish to do with the data you have accessed. After you 
enter the EDIT subcommand: 


input 


data lines that you enter are considered input to the file. To return 
to edit mode, you must enter a null line. 


If you issue the EDIT subcommand: 
cms 
the editor responds: 
CMS SUBSET 
and your virtual machine is in CMS subset mode, where you can issue any 


valid CMS subset command, that is, a CMS command that is allowed in CMS 
subset mode. These include: 


ACCESS | NAMEFIND | RDR 
CP | NAMES | RDRLIST 
DISK | NOTE READCARD 
ERASE | NUCXDROP | RECEIVE 
EXEC | NUCXLOAD | SENDFILE 

| EXECIO | NUCXMAP SET 

| FILELIST | PEEK STATE 

| GLOBALYV PRINT STATEW 

| IDENTIFY PUNCH | TELL 
LISTFILE QUERY TYPE 


You can also issue CP commands. To return to edit mode, you use the 
special CMS subset command, RETURN. If you enter the Immediate command 
HX, your editing session is terminated abnormally and your virtual 
machine is returned to the CMS environment. 


When you are finished with an edit session, you return to the CMS 
environment by issuing the FILE subcommand, which indicates that all 
modifications or data insertions that you have made should be written 
onto a CMS disk, or by issuing the subcommand QUIT, which tells the 
editor not to save any modifications or insertions made since the last 
time the file was written. 


More detailed information about EDIT subcommands and how to use the 


CMS editor is contained in this publication in "Section 5. The Editors" 
and in the VM/SP CMS Command and Macro Reference. 
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DEBUG 


CMS DEBUG is a special CMS facility that provides subcommands' to help 
you debug programs at your terminal. Your virtual machine enters the 
debug environment when you issue the CMS command: 


debug 


You may want to enter this command after you have loaded a program into 
storage and before you begin executing it. At this time you can set 
"breakpoints," or address stops, where you wish to halt your progran's 
execution so that you can examine and change the contents of general 
registers and storage areas. When these breakpoints are encountered, 
your virtual machine is placed in the debug environment. You can also 
enter the debug environment by issuing the CP EXTERNAL command, which 
causes an external interrupt to your virtual machine. 


Valid DEBUG subcommands that you can enter in this environment are: 


BR EAK GO RETURN 
CAW GPR SET 
CSW HX STORE 
DEFINE ORIGIN x 

DUMP PSW 


You can also use the #CP function in the debug environment to enter CP 
commands. 


You leave the debug environment in any of the following ways: 


e If the program you are running completes execution, you are returned 
to the CMS environment. 


e If your virtual machine entered the debug environment after a 
breakpoint was encountered, it returns to CMS when you issue the 
DEBUG subconmmand: 


hx 
To continue the execution of your program, you use the DEBUG 
subconmmand: 

go 


e If your virtual machine is in the debug environment and is not 
executing a program, the DEBUG subcommand: 


hx 


returns it to the CMS environment. 


CHS/DOS 


If you are a VSE/AF user, the CMS/DOS environment provides you with all 
the CMS interactive functions and facilities, as well as special CMS/DOS 
commands which Simulate DOS functions. The CMS/DOS environment becomes 
active when you issue the command: 


set dos on 


\ / 
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When your virtual machine is in the CMS/DOS environment you can issue 
any command line that would be valid in the CMS environment, including 
the facilities of EDIT, DEBUG, and EXEC, but excluding CMS commands or 
program modules that load and/or execute programs that use OS macros or 
functions. 


The following commands are provided in CMS/DOS to test and develop 
DOS programs, and to provide access to VSE/AF libraries: 


ASSGN DSERV OPTION 
DLBL ESERV PSERV 
DOSLIB FETCH RSERV 
DOSLKED FCOBOL SSERV 
DOSPLI LISTIO 


Your virtual machine leaves the CMS/DOS environment when you issue 
the command: 


set dos off 


If you reload CMS (with an IPL command) during a terminal session, you 
must also reissue the SET DOS ON command. 


Interrupting Program Execution 


When you are executing a program under CMS or executing a CMS command, 
your virtual machine is not available for you to enter commands. There 
are, however, ways in which you can interrupt a program and halt its 
execution, either temporarily, in which case you can resume its 
execution, or permanently, in which case your virtual machine returns to 
the CMS environment. In both cases, you interrupt execution by creating 
an "attention interruption," which may take two forms: 


e An attention interruption to your virtual machine operating systen 
e An attention interruption to the control progran 


These situations result in what are known as virtual machine (VM) or 
control program (CP) "reads" being presented to your virtual console. 
On a typewriter terminal, the keyboard unlocks when a read occurs. 


Whether you have to press the Attention key once or twice depends on 
the terminal mode setting in effect for your virtual machine. This 
setting is controlled by the CP TERMINAL command: 


cp terminal mode vn 


The setting VM is the default for virtual machines; you do not need to 
specify it. The VM setting indicates that one depression of the 
Attention key sends an interruption to your virtual machine, and that 
two depressions results in an interruption to the control program (CP). 


The CP setting for terminal mode, which is the default for the systen 
operator, indicates that one depression of the Attention key results in 
an interruption to the control program (CP). If you are using your 
virtual machine to run an operating system other than CMS, you might 
wish to use this setting. Issue the command: 


cp terminal mode cp 
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VIRTUAL MACHINE INTERRUPTIONS 


While a command or program is executing, if you press the Attention key 
once on a 2741 (or the Enter key on a 3270), you have created a virtual 
machine interruption. The program halts execution, your terminal will 
accept an input line, and you may: 


e Terminate the execution of the program by issuing an Immediate 
command to halt execution: 


hx 
The HX command causes the program to abnormally terminate (abend). 


e Enter a CMS command. The command is stacked in a console buffer and 
is processed by CMS when your program is finished executing and the 
next virtual machine read occurs. For example: 


print abc listing 
After you enter this line, the program resumes execution. 


e If the program is directing output to your terminal and you wish only 
to halt the terminal display, use the Immediate command: 


ht 


The program resumes execution. Terminal output can also be 
suppressed immediately when you enter a command by placing #HT at the 
end of the command line. The logical line end character (#) allows 
the Immediate command HT to be accepted; program execution proceeds 
without typing. 


You can, if you want, cause another interruption and request that 
typing be resumed by entering the RT (resume typing) command: 


rt 


e Enter a null line; your program continues execution. The null line is 
stacked in the console stack and read by CMS as a_ stacked command 
line. 


HX, HT, and RT are three of the CMS Immediate commands. They are 
"immediate" because they are executed aS soon as they are entered. 
Unlike other commands, they are not stacked in the console buffer. You 
can only enter an Immediate command following an attention interruption. 


CONTROL PROGRAM INTERRUPTIONS 


You can interrupt a program and enter the CP environment directly by 
pressing the Attention key twice quickly, on a 2741, or pressing the PA1 
key on a 3270. Then, you can enter any CP command. To resume the 
program's execution, issue the CP command: 


cp begin 


If your terminal is operating with the terminal mode set to CP, pressing 
the Attention key once places your virtual machine in the CP 
environment. 
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ADDRESS STOPS AND BREAKPOINTS 


A program may also be interrupted by an instruction address stop, which 
you specifically set by the CP command ADSTOP. For example, if you 
issue the command: 


cp adstop 201ea 


an address stop is set at virtual storage location X'201EA'. When your 
program reaches this address during its execution, it is interrupted and 
your virtual machine is placed in the CP environment, where you can 
issue any CP command, including another ADSTOP command, before resuming 
your program's execution with the CP command BEGIN. 


Breakpoints, similar to address stops, are set using the DEBUG 
subcommand BREAK, which you issue in the debug environment before 
executing a program. For example, if you issue: 


break 1 201ae 


your program's execution is interrupted at this address and your virtual 
machine is placed in the debug environment. You can then enter any 
DEBUG subcommand. To resume program execution, use the DEBUG subcommand 
GO. If you want to halt execution of the program entirely, use the 
DEBUG subcommand HX, which returns your virtual machine to the CMS 
environment. You can find more information about setting address stops 
and breakpoints in "Section 11. How VWM/SP Can Help You Debug Your 
Programs." 
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Section 3. What You Can Do With VM/SP-CMS Commands 


This section provides an overview of the CMS and CP command languages, 
and describes the various commands within functional areas, with 
examples. The commands are not presented in their entirety, nor isa 
complete selection of comgands represented. 


When you finish reading this section you should have an understanding 
of the kinds of commands available to you, so that when you. need to 
perform a particular task using CMS you may have an idea of whether it 
can be done, and know what cogmand to reference for details. For 
complete lists of the CP and CMS commands available, see "Appendix A: 
Summary of CMS Commands" and “Appendix B: Summary of CP Commands." 


Command Defaults 


Many of the characteristics of your CMS virtual machine are already 
established when you log on, but there are commands available so you can 
change them. In the case of many CMS commands, there are implied values 
for operands, so that when you enter a command line without certain 
operands, values are assumed for then. In both of these instances, the 
values set or implied are considered default values. As you learn CP 
and CMS commands, you also should become familiar with the default 
values or settings for each. 


Commands to Control Terminal Communications 


Using VM/SP, you control your virtual machine directly from your 
terminal. VM/SP provides a set of commands for terminal communications. 


ESTABLISHING AND TERMINATING COMMUNICATIONS WITH VA/SP 


To initiate your communication with VM/SP, use the CP LOGON command: 
cp logon san 
Optionally, you may enter your password on the same line!; 
cp logon sam 123456 
When you are sure that your communication line is all right and you have 
difficulty logging on (for example, someone else has logged on under 


your userid), you can use the CP MESSAGE command: 


cp message sam thisS iS san...pls log off 


1Note that. the password cannot be entered on the command line if the 
password suppression facility was specified at sysgen. 
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Another way to access the VM/SP system is to use the CP command DIAL: 

cp dial tsosys 
In this example, TSOSYS is the userid of a virtual machine running a TSO 
systen. After this DIAL command is successful, you can use _ your 


terminal as if you were actually connected to a TSO system, and you can 
begin TSO logon procedures. 


To end your terminal session, use the CP command LOGOFF: 
cp logoff 


If you have used a switched (or dial-up) communication path to the VM/SP 
computer and you want the line to remain available, you can enter: 


cp logoff hold 
At times, you might be running a long program under one userid and wish 
to use your terminal for some other work. Then, you can disconnect your 
terminal: 

cp disconn 

cp disconn hold 
Your virtual machine continues to run, and is logged off the system when 
your program has finished executing. If you want to regain terminal 
control of your virtual machine after disconnecting, log on as you would 
to initiate your terminal session. Your virtual machine is placed in 
the CP environment, and to resume its execution, you use the CP command 
BEGIN. 

You should not disconnect your virtual machine if a program requires 


an operator response, since the console read request cannot be 
satisfied. 


CONTROLLING TERMINAL OUTPUT 


During the course of a terminal session, you can receive many kinds of 
messages from VM/SP, from the system operator, from other users, or fron 
your own programs. You can decide whether or not you want these 
messages to actually reach you. For example, if you use the command: 

cp set msg off 
no one will be able to send messages to you with the CP MESSAGE command; 
if another virtual machine user tries to send you a message, he receives 
the message: 

userid NOT RECEIVING, MSG OFF 


If your virtual machine handles special messages and you do not want to 
receive special messages at this time, you can issue: 


cp set smsg off 
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No one will be able to send special messages to you with the CP SMSG 
command; if another virtual machine user attempts to do so, he receives 
a message: 


userid NOT RECEIVING, SMSG OFF 


Similarly, you can use: 

cp set wng off 
to prevent warning messages (which usually come from the _ systen 
operator) from coming to you. You would probably do this, however, only 


in cases where you were typing some output at your terminal and did not 
want the copy ruined. 


VM/SP issues error messages whenever you issue a command incorrectly 
or if aocommand or program fails. These messages have a long forn, 
consisting of the error message code and number, followed by text 
describing the error. If you wish to receive only the text portion of 
messages with severity codes I, E, and W (for informational, error, and 
warning, respectively), you can issue the command: 

cp set emsg text 
If you want to receive only the message code and number (from which you 
can locate an explanation of the error in VM/SP System Messages and 
Codes), you specify: 
cp set emsg code 
You can also cancel error messages completely: 
cp set emsg off 


To restore the EMSG setting to its default, which is the message text, 
enter: 


cp set emsg text 
Some CP commands issue informational messages telling you that CP has 
performed a particular function. You can prevent the reception of these 
messages with the command: 
cp set imsg off 
or restore the default by issuing: 
cp set imsg on 


The setting of EMSG applies to CMS commands as well as to CP commands. 
You can also control the format of the CMS ready message. If you 
enter: 
set rdymsg smsg 
you receive only the "R;" or shortened form of the ready message after 
the completion of CMS commands. If you are not receiving error messages 


(as described above) andan error occurs, the return code fron the 
command still appears in parentheses following the "R". 
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An additional feature exists for CMS. If you have a_ typewriter 
terminal with a two-color ribbon, you can specify: 


set redtype on 
so that CMS error messages are typed in red. 

Some commands or messages result in displays of lines that are very 
long. If you want to limit the width of lines that are received at your 
terminal (for example, if you are using terminal paper that is only 
eight inches wide), you can specify: 


cp terminal linesize 80 


so that all lines received at your terminal are formatted to fit within 
an 80-character display. 


You can also control two special characters in VM/SP. One is the 
exclamation point (!) that types when the Attention key is pressed. If 


you do not want this character to type when you press the Attention key, 
use the command: 


cp terminal attn off 


CMS allows you to specify a "blip character: this character is typed 
or displayed whenever two seconds of processor time are used by your 
virtual machine. If you enter: 


set blip * 


then, during program execution, this character types for every two 
seconds of CPU time. You can cancel the function: 


set blip off 


or set it to nonprintable characters: 


set blip on 


When this command has been entered on a typewriter terminal, the 
Selectric type ball tilts and rotates whenever a blip character is 
received. 


Note: Issuance of the STIMER macro for more than two seconds will mask 
off blips. 


On a display terminal, you can control the intensity of the redisplay 
of user input. If you enter: 


cp terminal hilight on 
the redisplay of user input is highlighted. If you enter: 
cp terminal hilight off 
the redisplay of user input is at normal intensity. This is’ the 


default. 
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COMMANDS TO CONTROL HOW VB/SP PROCESSES INPUT LINES 


You can 


own needs. In addition 


Manipulate VM/SP"s logical line 
to using the CP TERMINAL command to change the 


editing function to suit your 


default logical line editing symbols, you can issue: 


cp set linedit off 


so that none of the symbols are recognized by VM/SP 


your input lines. 


When you are in 
that you can use 
command functions 


to control how 


the CMS environment, 
CMS validates a 
IMPCP (implied CP) 


when it interprets 


number of commands 
command line. The SET 
and IMPEX (implied EXEC) control 


there are a 


the recognition of CP commands and CMS EXEC procedures. For example, if 
you issue: 

set impcp off # set impex off 
then, when you enter CP commands in CMS or try to execute EXEC 
procedures, you must preface the name of the command or procedure with 
CP (or #CP), or EXEC, respectively. 


By using the SYNONYM and the SET ABBREV commands, you 


what command names, synonyms, 
example, you could set up a file 
following records: 


or 


can control 


truncations are valid in CMS. For 


Named MYSYN SYNONYM which contains the 


PRINT PRT 1 

RELEASE LETGOOF 5 

ACCESS GET 1 

DOSLKED LNKEDT 3 
The first column specifies an existing CMS command, module, or EXEC 
Name; the second column specifies the alternate name, or synonym, you 


want to use; and the third column 
Mininum number of 


the name. 
synonym mysyn 

you can use PRT, LETGOOF, and 

CMS command names. Also, 

the default; you can make sure it 

SET ABBREV ON), you can truncate 


number of characters specified in 
is, you could enter "p" for PRINT, 


GET, 


You can set up CMS EXEC files 
that may or may not perform the 
duplicate. For example, if every 
used the same operands, you could 
that contained a single record: 


global maclib cmslib osmacro 


if the ABBREV 


is a count field that indicates the 


characters of the synonym that can be used to truncate 
Using this file, after you enter the command: 


LNKEDT in place of the corresponding 
function is in effect, (it is 
is in effect by issuing the command 
any of your synonyms to the nininun 
the count field of the record (that 
"letgo" for RELEASE, and so on). 


with the same names as CMS commands, 
Same function as the CMS names they 
time you used the GLOBAL command you 
have a CMS EXEC file, named GLOBAL, 


Then, every time you entered the command name: 


global 


the command GLOBAL 
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MACLIB CMSLIB OSMACRO would execute. 
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As another example, suppose you had an EXEC file named ‘'T*, that 
contained the following records: 


SCONTROL OFF 
CP QUERY TIME 


Then, whenever you entered: 
t 


you would receive the CP time-of-day message, and you could no longer 
use the truncation "Tf" for the CMS command TYPE. In order to see the 
contents of acCMS file displayed at your terminal you would have to 
enter at least "TY" as a truncation. 


CONTROLLING KEYBOARD-DEPENDENT COMMUNICATIONS 


You are dependent on your terminal for communication with VM/SP: when 
your virtual machine is waiting fora read either from the control 
program or from your virtual machine operating system, you can not 
receive messages until you press the Return key to enter a command or a 
null line. If you are in a situation where you must wait for a message 
before continuing your work, for example, if you are waiting for a tape 
device to be attached to your virtual machine, you can use the CP 
command SLEEP to lock your keyboard: 


cp sleep 


You must then press the Attention key to get out of sleep and unlock the 
keyboard so you can enter a command. 


If your virtual machine is in the CP environment when you issue the 
SLEEP command, or if you issue the SLEEP command from the CMS 
environment using the #CP function, your virtual machine is in the CP 
environment after you press the Attention key. If your virtual machine 
is in the CMS environment when you enter the SLEEP command (or if you 
enter CP SLEEP), your virtual machine is in the CMS environment when you 
press the Attention key once. 


You can control the effect of pressing the Attention key on your 
terminal with the CP TERMINAL command. If you specify: 


cp terminal mode cp 


then, whenever you press the Attention key, you are in the CP 
environnent. 


If you use the default terminal mode setting, which is VM, and then 
you press the Attention key once, you cause a read to your virtual 
machine; if you press’ the Attention key twice you cause a CP read, and 
you are in the CP environment. 


The effect of pressing the Attention key is also important when you 
are executing a program. At times, you may wish to enter some CP 
commands while your program executes, but you do not want to interrupt 
the execution of the progran. If, before you begin your program you 
issue the command: 


cp set run on 
and then use the Attention key to get to the CP environment while your 


program executes, the program continues executing while you communicate 
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with CP. The default setting for the RUN operand of the SET command is 
off; usually, when you press the Attention key (twice) during program 
execution, your program is interrupted. 


SPECIAL CHARACTER SETS: If you are using a programming language or 
entering data that requires you to use characters that are not on your 
keyboard, you can select some characters that you do not use very often 
and establish a translate table with the SET command. For example, if 
your terminal does not have the special characters [ and ] (which have 
the hexadecimal values AD and BD, respectively), you could issue the 
commands: 


set input % ad 
set input $ bd 


Then, when you are entering data lines at your terminal, whenever you 
enter the characters "%" or "$", they are translated and written into 
your file as "[" and "]". When you display these lines, the character 
positions occupied by the special characters appear to be blanks, 
because they are not available on your keyboard. If you want these 
special characters to appear on your terminal in symbolic form, you 
should issue the commands: 


set output ad % 
set output bd $ 


so that when you are displaying lines that contain these characters, 
they will appear translated as % and $ on your terminal. If you are 
going to use the input and output functions together, you must set the 
output character first; if you set the input character first, then you 
are unable to set the output function. 


If you are using CMS to develop application programs (COBOL, FORTRAN, 
etc.), remember when entering data from a terminal that a null line 
results in an end-of-file (EOF) entry into your file. 

If you are an APL user and have the special APL type font or the APL 
3270 feature and keyboard, you can tell VM/SP to use APL translation 
tables with the command; 


cp terminal apl on 


Commands to Create, Modify, and Move Data Files and Programs 


The CMS command language provides you with many different ways of 
Manipulating files. A file, in CMS, is any collection of data; it is 
most often a disk file, but it may also be contained on cards or tape, 
or it may be a printed or punched output file. 


COMMANDS THAT CREATE FILES 


You create files in CMS by several methods; either specifically or by 
default. The EDIT command invokes the CMS editor to allow you to create 
a file directly at your terminal. You must specify a file identifier 
when you are creating a new file: 

edit mother goose 


In this example, the file has an identifier, or fileid, of MOTHER GOOSE. 
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The EDIT subcommand INPUT allows you to begin inserting lines of data or 
source code into this file. When you issue the subcommands FILE or 
SAVE, the lines that you have entered are written into a CMS disk file. 


Files are created, and sometimes named, by default, with the 
following types of commands: 


e Commands that invoke programming language processors or compilers. 
For example, if you issue the command: 


assemble myfile 


the assembler assembles source statements from an existing CMS file 
named MYFILE ASSEMBLE and produces an output file containing object 
code, as well as a listing. The files that are created are naned: 


MYFILE TEXT 
MYFILE LISTING 


e Commands that load CMS files onto a disk from cards or tapes. These 
commands are READCARD, TAPE LOAD, and DISK LOAD. 


e The LISTFILE and LISTIO commands with the EXEC option create files 
named CMS EXEC and $LISTIO EXEC which you can execute as_ EXEC 
procedures. 


e The TAPPDS and TAPEMAC commands create CMS disk files from OS data 
sets on tape. If the data set is a partitioned data set, the TAPPDS 
command creates individual CMS files from each of the members; the 
TAPEMAC command creates a CMS macro library, called a MACLIB, from an 
OS macro library. 


e The MOVEFILE and FILEDEF commands, used together, can copy OS or DOS 
data sets or files into CMS files; they can also copy files fron 
cards or tapes. 


e CMS/DOS commands SSERV, ESERV, RSERV, and PSERV copy DOS files fron 
source statement, relocatable, and procedure libraries into CHS 
files. 


e Some CMS commands produce maps, or lists of files, data sets, or 
program entry points. For example, if you issue the command: 


tape scan (disk 

a CMS disk file named TAPE MAP is created that contains a list of the 

CMS files that exist on a tape attached to your virtual machine at 

virtual address 181. 

Some commands create new files from files that already exist on your 
Virtual disks. The creation may involve a simple copy operation, or it 
may be a combining of many files of one type into a larger file of the 
same or a different type: 


e The COPYFILE command, in its simplest form, copies a file from one 
virtual disk to another: 


copyfile yourprog assemble b myprog assemble a 


e The MACLIB and TXTLIB commands create libraries from MACRO or COPY 
files, or from TEXT (object) files. 


e The SORT command rearranges (in alphameric sequence) the records in a 
file and creates a new file to contain the result. You have to 
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specify the name of the new file: 
sort nonseq recs a seq recs a 
e The GENMOD command creates nonrelocatable modules from object modules 
that you have loaded into your virtual storage area. For example, 
the commands: 


load test 
genmod payroll 


create a file named PAYROLL MODULE, which you can then execute as a 
user-written CMS command. 


e The DOSLKED command creates or adds members to DOSLIBS, which are 
libraries containing link-edited CMS/DOS program phases. 


e The UPDATE command creates an updated source file and special update 
files when you use it to apply updates to your source programs. 


COMMANDS THAT MODIFY DISK FILES 
You can use the CMS Editor to modify existing files on your virtual 
disks. You issue the EDIT command, giving the file identifier: 
edit old file 
CMS editor subcommands allow you to make minor specific changes or 


global changes, which can affect many lines in a file at one time. 


The MACLIB and TXTLIB commands also allow you to modify CMS macro and 
text libraries. You can add, delete, or replace members in these 
libraries using these commands. 

The COPYFILE command has some options that allow you to change a file 
without creating a new output file. For example, if you enter the 
command: 

copyfile my file a (lowcase 


then all of the uppercase characters in the file MY FILE are translated 
to lowercase. 


You can change the file identifier of a file using the RENAME 
command: 


rename test file a1 good file al 
The ERASE command deletes files from your virtual disks: 

erase temporary file b1 
For additional examples of CMS file system commands, see “Appendix D: 
Sample Terminal Sessions." 


COMMANDS TO MOVE FILES 


You can use CMS commands to transfer a data file from one device or 
medium to another device of the same or of a different type. The types 
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of movement and the commands to use are described briefly here and in 
detail in "Section 7. Using Real Printers, Punches, Readers, and Tapes." 


If you need to transfer files between virtual machines, you can use 
the SENDFILE, PUNCH, or DISK commands to punch virtual card image 
records. These are then placed in the virtual card reader of the 
receiving virtual machine. 


Before you use PUNCH or DISK commands, you must indicate the output 

disposition of the files. You do this with the CP SPOOL command: 

cp spool 00d to mickey 
Then, you can use the PUNCH command to punch virtual card images: 

punch acct records 
The file ACCT RECORDS is spooled to the userid MICKEY's virtual card 
reader. If the CMS file you are transferring does not have fixed- 
length, 80-character (card image) records, you can use the command: 


disk dump acct records 


The CMS TAPE command allows you to dump CMS files onto tape, or to 
restore previously dumped files: 


tape dump archive file 
tape load archive file 


VM/SP also provides a special utility program, DASD Dump Restore 
(DDR), that allows you to dump the entire contents of your virtual disk 
onto a tape and then later restore it toa disk. You might use this 


program, invoked by the DDR command in CMS, to back up your data files 
before using them to test a new progran. 


COMMANDS TO PRINT AND PUNCH FILES 
The commands that you use most often to print and punch CMS files are 
the commands PRINT and PUNCH. For example: 
print myprog listing 
prints the contents of the LISTING file on the system printer, and: 
punch myprog assemble 


punches the assembler language source statement file onto cards. You 
can also punch members of MACLIBs and TXTLIBs: 


punch cmslib maclib (member fscb 
Some CMS commands have a PRINT option, so that instead of having some 
kinds of output displayed at your terminal or placed in a disk file, you 
can request to have it printed on the real system printer. For example, 


if you want a list of the contents of a macro library to print, you 
could issue the command: 


mMaclib map mylib (print 


You can see the contents of a file displayed at your terminal by 
using the TYPE command: 


34 IBM VM/SP CMS User's Guide 


type week3 report 


You can specify, on the TYPE command, that you want to see only Some 
specific records in this file: 


type week3 report a 1 20 


Commands to Develop and Test OS and CMS Programs 


Use CMS to prepare programs: you can create them with the CMS editor, or 
write them onto your CMS disks using any of the methods discussed above. 
You can also assemble or compile source programs directly from cards, 
tapes, or OS data sets. If your source program is ina CMS disk file, 
then during the development process you can use the editor to make 
corrections and updates. 


To compile your programs, use the assembler or any of the language 
processors available at your installation. If your program uses macros 
that are contained in either system or private program libraries, you 
must make these libraries known to CMS by using the GLOBAL command: 


global maclib cmslib asmlib 


In this example, you are using two libraries: the CMS macro library, 
CMSLIB MACLIB, and a private library, named ASMLIB MACLIB. 


The output from the compilers, in relocatable object forn, is stored 
on a CMS disk as a file with the filetype of TEXT. To load TEXT files 


into the user area of virtual storage to execute them, use the LOAD 
command: 


load nyprog 
The LOAD command performs the linkage editor function in CMS. If 

MYPROG contains references to external routines, and these routines are 
the names of CMS TEXT files, those TEXT files are automatically included 
in the load. If you receive a message telling you that there is an 
undefined name (which might happen if you have a CSECT name or entry 
point that is not the same as the name of the TEXT file that contains 
it), you can then use the INCLUDE command to load this TEXT file: 

include scanrtn 


When you have loaded the object modules into storage, you can begin 
program execution with the START command: 


start 
If you want to begin execution at a specified entry point, enter: 
Start scant 
where SCAN1 is the name of a control section, entry point, or procedure. 
If you are testing a program that either reads or writes files or 
data sets using OS macros, you must use the FILEDEF command to supply a 
file definition to correspond to the ddname you specify in your progran. 
The command: 


filedef indd reader 


indicates that the input file is to be read from your virtual card 
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reader. A disk file might be defined: 


filedef outdd disk out file a1 The FILEDEF command in CMS performs 
the same function as a data definition (DD) card in OS. 


The commands to load and execute OS programs are discussed in 
"Section 8. Developing OS Programs Under CMS." 


The RUN command, which is actually a CMS EXEC procedure, combines 
Bany of these commands for you, so that if you want to compile, load, 
and execute a single source file, or load and execute a TEXT or MODULE 
file, you can use the RUN command instead of issuing a series of 
commands. See the discussion of the RUN command in VM/SP CMS Command and 
Macro Reference for a list of the OS language processors available. 


Commands to Develop and Test DOS Programs 


CMS simulates many functions of VSE/AF in the CMS/DOS environment. 
CNS/DOS is not a separate system, but is part of CMS. When you enter the 
command: 


set dos on 
you are in the CMS/DOS environment. If you want to use the libraries on 
the VSE/AF system residence volume, you should access the disk on which 
it resides and specify the mode letter on the SET DOS ON command line: 


access 132 c 
set dos onc 


Using commands that are available only in the CMS/DOS environment, 
you can asSign system and programmer logical units with the ASSGN 
command: 

assgn sys200 reader 


If the device is a disk device, you can set up a data definition with 
the DLBL command: 


assgn sys100 b 
dlbl infile b dsn nyinput.file (sys100 


You can find out the current logical unit assignments and active file 
definitions with the LISTIO and QUERY DLBL commands, respectively: 


listio a 
query dlbl 


If you are an assembler language programmer, you can assemble a 
source file with the ASSEMBLE command: 


assemble myprog 
A CMS file with a filetype of DOSLIB simulates a DOS core image 
library; you can link-edit TEXT files or relocatable modules from a DOS 
relocatable library and place the link-edited phase in a DOSLIB using 
the DOSLKED command: 


doslked myprog hewlib 
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Then, use the GLOBAL command to identify the phase library and issue the 
FETCH command to bring the phase into virtual storage: 


global doslib newlib 
fetch myprog 


The START command begins program execution: 
start 


During program development with CMS, you can use VSE/AF system or 
private libraries. You can use files on these libraries or you can copy 
them into CMS files. The DSERV command displays the directories of 
VSE/AF libraries. The command: 


dserv cd 


produces a copy of the directory for the core image library. To copy 
phases from relocatable libraries into CMS TEXT files, you could use the 
RSERV command: 


rserv oldprog 


The SSERV and ESERV commands are available for you to copy files fron 
source statement libraries, or copy and de-edit macros from E&E 
sublibraries. Also, the PSERV command copies procedures from the 
procedure library. 


The CMS/DOS commands are described in detail in "Section 9. 
Developing DOS Programs Under CMS." 


Commands Used in Debugging Programs 


When you execute your programs under CMS, you can debug them as they 
execute, by forcing execution to halt at specific instruction addresses. 
You do this by entering the debug environment before you issue the START 
command. You enter the debug environment with the DEBUG command: 


debug 


To specify that execution be stopped at a particular virtual address, 
you can use the BREAK subcommand to set a breakpoint. For example: 


break 1 20ad0 


Then, when this virtual address is encountered during the execution of 
the program, the debug environment is entered and you can examine 
registers or specific storage locations, or print a dump of your virtual 
storage. Subcommands that do these things might look like the 
following: 


gpr 0 15 
x 20c12 8 
dump 20000 * 


Instead of using the CMS DEBUG subcommands, you can use the CP ADSTOP 
command to set address stops. For example: 


cp adstop 20ad0 
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Then, in the CP environment, you can use CP commands to do the same 
things. For example: 


cp display g 
cp display 20c12.8 
cp dump 20000 


Both sets of commands shown in these examples result in displays of (1) 
the contents of your virtual machine's general purpose registers, (2) a 
display of eight bytes of storage beginning at location X'20C12' and (3) 
a dump of virtual storage from location X*20000* to the end. 


You can also use the CMS SVCTRACE command and the CP TRACE commands 
to see a record of interruption activity in your virtual machine. 


The DEBUG subcommands and the CMS and CP debugging facilities are 
described in more detail in "Section 11. How VM/SP Can Help You Debug 
Your Programs." 


Commands to Request Information 


All of the CP and CMS commands discussed in this section have required 
some action on your part: you set your terminal characteristics, 
manipulate disk files, develop, compile, and test programs, and control 
your virtual machine devices and spool files. During a terminal session 
you can change the status of many of your devices and virtual machine 
characteristics, modify the files on your disks and create spool files. 
VMN/SP provides many commands to help you find out what is and what is 
not currently defined in your virtual machine. 


COMMANDS TO REQUEST INFORMATION ABOUT TERMINAL CHARACTERISTICS 


You can find out the status of your terminal characteristics by using 
the CP command QUERY with the TERMINAL or SET operands. If you issue the 
command: 

cp query terminal 
you can see the settings for all of the functions controlled by the CP 
TERMINAL command, including the current line size and line editing 
symbols. 

Similarly, the command: 
cp query set 


tells you the settings for the functions controlled by the CP SET 
command, such as error message display, and the MSG and WNG flags. 


For most of the functions controlled by the CMS SET command, there 
are corresponding CMS QUERY command operands; to find out a particular 
setting, you must specify the function in the QUERY command. For 
example: 


query input 
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lists the current settings in effect for input character translation. 
Other functions that you can query this way are: 


BLIP INPUT REDTYPE 
IMPCP . OUTPUT SYNONYA 
IMPEX RDYMSG 


‘COMMANDS TO REQUEST INFORMATION ABOUT DATA FILES 


Use the LISTFILE command to get information about CMS files. The 
information you can obtain from the LISTFILE command includes; 


ee Oe ee a ee Pe pr Se Ne EI ee eR ey SiS eT Rep Se ee tee eT ae oT ee a Re a — 
jlistfile {Names of all of the files on your A-disk. | 
Nee 
Jlistfile * * b [Names of all the files on your accessed B-disk. | 


$$ tp 
[listfile myprog * [Names of all of the files on your A-disk | 
[ [with a filename of myprog. | 


|listfile * assemble |Names of all of the files on your A-disk | 
| jwith a filetype of assemble. | 


[|-——____-—_—__ 4 Oo 0 Ol nl 
[|listfile * * a1 [Names of all of the files on your A-disk | 
[ jwith the filemode number of 1. | 


|listfile * * (label |The record length, record format, blocksize, | 
| [creation date, and disk label for each of the [ 


| |files on your A-disk. | 
a 


Also see the CMS command FILELIST in the CMS Command and Macro 
Reference. In a full screen environment, FILELIST provides you with 
the same information as the LISTFILE command. 


Use the STATE command to find out whether a certain file exists: 
state sales list c 


If you want to know if the file is on a read/write disk, you can use 
the STATEW command. 


To find out what CMS libraries have been made available, you can use 
the commands: 


query doslib 
query maclib 
query txtlib 
query library 


To find out what members are contained in a particular macro or text 
library use the commands: 


Maclib map mylib (term 
txtlib map proglib (tern 
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The MODMAP command displays a load map of a MODULE file: 
modmap payroll 


To examine load maps created by the LOAD command, use the TYPE 
command: 


type load map a5 
The TYPE command can also be used to display the contents of any CMS, 
file. To examine large files, you can use the PRINT command to spool a 
copy to the high-speed printer. 


To compare the contents of two files to see if they are identical, 
use the COMPARE command: 


compare labor stat a1 labor stat b1 


Any records in these files that do not match are displayed at your 
terminal. 


If you have OS or DOS disks attached to your virtual machine, you 
can display a list of OS data sets or DOS files by uSing the LISTDS 
command; for example; 

listds d 


displays alist of the data sets or files on the OS or DOS disk 
accessed as your D-disk. 


COMMANDS TO REQUEST INFORMATION ABOUT YOUR VIRTUAL DISKS 


Use the CP QUERY command to find out: 
e What virtual disks are currently part of your configuration: 
cp guery virtual dasd 
e Whether a particular virtual disk address is in use: 
cp query virtual 291 
e What users might be linked to one of your disks: 
cp query links 330 


The CMS QUERY command can tell you about your accessed disks. If you 
enter: 


query disk a 
you can find out the number of files on your A-disk, the amount of space 
that is being used, and its percentage of the total disk space, and the 
read/write status. To get this information for all of your accessed 
disks, issue the command: 


query disk * 


To obtain information about the extents occupied by files on OS and DOS 
disks, enter the command: 


listds * (extent 
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If you want to know the current order in which your disks are 
searched for data files or programs, issue the command: 


query search 
You could also use this command to find out what disks you have 


accessed, what filemode letters you have assigned to them, whether they 
are read/write or read-only, and whether they are CMS, OS, or DOS disks. 


COMMANDS TO REQUEST INFORMATION ABOUT YOUR VIRTUAL MACHINE 


The conmand: 

cp query userid 
gives you your userid and the system identifier for the CPU you are 
using. The system identifier is a one to eight character name assigned 
by your location. The system identifier is not given if no name has 
been assigned. The CMS IDENTIFY command also can be used to display or 
Stack the userid, nodeid, rscsid, date, time, time zone, and day of the 
week. Refer to the VM/SP CMS Command and Macro Reference for more 
information. 
If you issue the command: 

cp query virtual 


you can find out the status of your virtual machine configuration. You 
can also request specific information; for example, the command: 


cp query storage 
gives you the amount of virtual storage you have available. 


To find out the current spooling characteristics of your printer, 
punch, or reader, issue the connands: 


cp guery 00e 
cp query 00d 
cp guery 00c 
To see information about all three at once, use: 


cp query ur 


For the status of spool files on any of these devices, issue the 
commands: 


cp query printer 
cp query punch 
cp query reader 


Using these commands, you can request the status of particular spool 
files by referring to the spoolid number; for example: 


cp query printer 4187 


You can also request additional information about the files, including 
file identification and creation tine: 


cp query reader all 
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Use the CMS RDR command to determine the characteristics of the next 
file in your virtual reader. For more information on the RDR command, 
refer to the VM/SP CMS Command and Macro Reference. 


If you want to know the total number of spool files associated with 
your virtual machine, you can use the command: 


cp query files 


The response to this message is the same as the message you receive if 
you have spool files when you 1og on. The RDRLIST EXEC procedure 
displays information about the files in your virtual reader with the 
ability to PEEK at them or RECEIVE them. Refer to the VM/SP CMS Command 
and Macro Reference for command information. 


COMMANDS TO USE TO COMMUNICATE WITH OTHER COMPUTER USERS 


Using CMS commands, you have the ability to send information to other 
users and to receive information from them. Information about other 
computer users with whom you communicate can be collected in your 
"userid Names" file. The following commands reference the NAMES file 
created by the NAMES command: NAMEFIND, NOTE, RECEIVE, SENDFILE, and 
TELL. 


a ee 
| NAMEFIND [Display/stack information from a NAMES file. | 

+ —__ 
| NOTE |Prepare a ‘note’ for one or more computer users, | 


| [to be sent via the SENDFILE command. | 
|-——-—__ ——__+--- HH 
[RECEIVE |Read onto disk a file or note that is in your | 
| |virtual reader. | 
$+ HI 
|SENDFILE |Send files or notes to one or more users, | 
| jattached locally or remotely, by issuing the | 
| |command or by using a menu. (display terminal only) | 
SSS SS eet 
| TELL |Send a message to one or more computer users who { 
l Jace logged on to your computer or to one attached | 


[ {to yours via RSCS. { 
| Reece eee es Ce ee re ee | 


The command formats and examples for each of the above commands are 
documented in the VM/SP CMS Command and Macro Reference. 
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Section 4. The CMS File System 


The file is the essential unit of data in the CMS systen. CMS disk 
files are unique to the CMS system and cannot be read or written using 
other operating systems. When you create a file in CMS, you name it 
using a file identifier. The file identifier consists of three fields: 


e Filename (fn) 
e Filetype (ft) 
e Filemode (fn) 


When you use CMS commands and programs to modify, update, or 
reference files, you must identify the file by using these fields. Some 
CMS commands require you to enter only the filename, or the filename and 
filetype; others require you to enter the filemode field as well. This 
section contains information about the things you must consider when you 
give your CMS files their identifiers, notes on the file system commands 
that create and modify CMS files, and additional notes on using CMS 
disks. 


CMS File Formats 


The CMS file management routines write CMS files on disk in fixed 
physical blocks, regardless of whether they have fixed- Or 
variable-length records. For most of your CMS applications, you never 
need to specify either a logical record length and record format or 
block size when you create a CMS file. 


When you create a file using one of the CMS editors, the file has 
certain default characteristics, based on its filetype. The special 
filetypes recognized by the editor, and their applications, are 
discussed under "What are Reserved Filetypes?" 


VSAM files written by CMS are in the same format as VSAM files 
written by OS/VS or VSE/AF and are recognized by those operating 
systems. You cannot, however, use any CMS file system commands to read 
and write VSAM files, because VSAM file formats are unique to the 
virtual storage access method. 


For a minidisk formatted in 800-byte physical blocks, a single CMS 
file can contain up to 12,848,000 bytes of data grouped into as many as 
65,533 logical records, all of which must be on the same minidisk. If 
the file is a source program, the file size limit may be smaller. The 
Maximum number of files per real disk in the 800-byte physical block 
format is 3400 for a 3330, 3333, 3340, or 3350 disk, or 3500 for a 2314 
or 2319. 


For a minidisk formatted in 1024-, 2048-, or 4096-byte logical 
blocks, a single CMS file can contain up to about (231 - 132,000) disk 
blocks of data, grouped into as many as 231-1 logical records, all of 
which must be on the same minidisk. 
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How CMS Files Get Their Names 


When you create a CMS file, you can give it any filename and filetype 
you wish. The rules for forming filenames and filetypes are: 


e The filename and filetype can each be from one to eight characters. 
e The valid characters are A-Z, 0-9, $, #, 0, t, -— (hyphen), : (colon), 
and (underscore). 


When you enter a command line into the VM/SP systen, VM/SP always 
translates your input line into uppercase characters. So, when you 
specify a file identifier, you can enter it in lowercase. 


Remember that, by default, the # and @ characters are line editing 
symbols in VM/SP; when you use them to identify a file, you must precede 
them with the logical escape symbol ("). 


The third field in the file identifier, the filemode, indicates the 
mode letter (A-2Z) currently assigned to the virtual disk on which you 
want the file to reside. When you use the CMS Editor to create a file, 
and you do not specify this field, the file you create is written on 
your A-disk, and has a filemode letter of A. 


The filemode letter, for any file, can change during a_ terminal 
session. For example, when you log on, your virtual disk at address 191 
is accessed as your A-disk, so a file on that disk named SPECIAL EVENTS 
has a file identifier of: 


SPECIAL EVENTS A 


If, however, you later access another disk as your A-disk, and access 
your 191 as your B-disk, then this file has a file identifier of: 


SPECIAL EVENTS B 


DUPLICATING FILENAMES AND FILETYPES 


You can give the same filename to as many files on a given disk as you 
want, as long as you assign them different filetypes. Or you can create 
many files with the same filetype but different filenames. 


For the most part, filenames that you choose for your files have no 
special significance to CMS. If, however, you choose a name that is the 
same as the name of a CMS command, and the file that you assign this 
hame to is an executable nodule or EXEC procedure, then you may 
encounter difficulty if you try to execute the CMS command whose nane 
you duplicated. 


For an explanation of how CMS identifies a command name,’ see "CMS 
Command Search Order" later in this section. 


Many CMS commands allow you to specify one or more of the fields ina 


file identifier as an asterisk (*) or equal Sign (=), which identify 
files with similar fileids. 
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Using Asterisks (*) in Fileids 


Some CHS commands that manipulate disk files allow you to enter the 
filename and/or filetype fields as an asterisk (*), indicating that all 
files of the specified filename/filetype are to be modified. These 
commands are: 


COPYFILE RENAME as 
ERASE TAPE DUMP 


For example, if you specify: 
erase * test a 


all files with a filetype of TEST on your A-disk are erased. The 
LISTFILE command allows you to request similar lists. If you specify an 
asterisk for a filename or filetype, all of the files of that filename 
or filetype are listed. There is an additional feature that you can use 
with the LISTFILE command, to obtain a list of all the files that have a 
filename or filetype that begin with the same character string. For 
example: 


listfile t* assemble 


produces a list of all files on your A-disk with filenames beginning 
with the letter T and with the filetype of assemble. The command: 


listfile tr* a* 


produces a list of all files on your A-disk with filenames beginning 
with the letters TR and with filetypes beginning with the letter A. 


The COMPARE, COPYFILE, RENAME, and SORT commands allow you to enter 
output file identifiers as equal signs (=), to indicate that it is the 
same as the corresponding input file identifier. For example: 


copyfile myprog assemble b==a 
copies the file MYPROG ASSEMBLE from your B-disk to your A-disk, and 
uses the same filename and filetype as specified in the input fileid for 
those positions in the output fileid. 
Similarly, if you enter the command: 
rename temp * b perm == all files with a filename of TEMP are 


renamed to have filenames of PERM; the existing filetypes of the files 
remain unchanged. 


What Are Reserved Filetypes? 


For the purposes of most CMS commands, the filetype field is used merely 
as an identifier. Some filetypes, though, have special uses in CMS; 
these are known as "reserved filetypes." 


Nothing prevents you from assigning any of the reserved filetypes to 
files that are not being used for the specific CMS function normally 
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associated with that filetype. 


Some reserved filetypes also have special significance to the CMS 
editor. When you use the EDIT command to create a file with a reserved 
filetype, the editor assumes various default characteristics for the 
file, such as record length and format, tab settings, translation to 
uppercase, truncation column, and so on. 


FILETYPES FOR CMS COMMANDS 


Reserved filetypes sometimes indicate how the file is used in the CMS 
system: the filetype ASSEMBLE, for example, indicates that the file is 
to be used as input to the assembler; the filetype TEXT indicates that 
the file is in relocatable object form, and so on. Many CMS commands 
assume input files of particular filetypes, and require you to enter 
only the filename on the command line. For example, if you enter: 


synonym test 


CMS searches for a file with a filetype of SYNONYM and a filename of 
TEST. A file named TEST that has any other filetype is ignored. 


Some CMS commands create files of particular filetypes, using the 
filename you enter on the command line. The language processors do this 
as well; if you are recompiling a source file, but wish to save previous 
output files, you should rename them before executing the command. 


Figure 3 lists the filetypes used by CMS commands and describes how 
they are used. Figure 4 lists the filetypes used by CMS/DOS commands. 


In addition to these CMS filetypes, there are special filetypes 
reserved for use by the language processors, which are IBM program 
products. These filetypes, and the commands that use them, are: 


Filetypes Commands 

COBOL, SYMDMP, TESTCOB COBOL, FCOBOL, TESTCOB 

FORTRAN, FREEFORT, FORTRAN, FORTGI, FORTHX 
FTnn001, TESTFORT GOFORT, TESTFORT 

PLI, PLIOPT DOSPLI, PLIC, PLICR, PLIOPT 

RPGIT RPGIT 

VSBASIC, VSBDATA VSBASIC 


For details on how to use these filetypes, consult the appropriate 
program product documentation. 
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Filetype 


Command 


ANSERV 


ASM3705 
GEN3705 


ASSEMBLE 


UPDATE 


UPDATE 


MACLIB 


DIRECT 


EXEC 
GEN3705 
LISTFILE 


DEFAULTS 
GLOBALV 


HELP 


AMSERV 
ASSEMBLE 
ASM3705 
COBOL 
DOSPLI 
FCOBOL 
LOADLIB 
PLIOPT 


LKED 


Comments 


Contains VSAM access method services control 
statements executed with the AMSERV command. 
command. 


Used by system programmers to generate the 
3704/3705 control progran. 


Contains source statements for assembler 
language programs. 


Points to files that contain UPDATE control 
Statements for multiple updates. 


Lists files that either contain UPDATE control| 
statements or point to additional files. [ 

[ 
Can contain COPY control statements and macros| 
or copy files to be added to MACLIBs. | 

l 
Contains entries for the VM/SP user directory | 
file.The system programmer controls this file. | 


Can contain sequences of CMS or user—written 
commands, with execution control statements. 


Contains variables used by GLOBALV. 


Contains descriptive information for CP and 
CMS commands, messages, EXEC and EXEC2 
statements, CMS Editor and System Product 
Editor subcommands, and menu lists. 


Listings are produced by the assembler, the 
language processors, and the AMSERV and 
LOADLIB commands. 


Contains the printer output from the LINK 
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Filetype 


LOADLIB 


MACLIB 


MACRO 


MAP 


MODULE 


NAMES 


NETLOG 


NOTEBOOK 


SYNONYA 


SCRIPT 


TEXT 


TXTLIB 


Command 


FILEDEF 
GLOBAL 
LKED 
LOADLIB 
NUCXLOAD 
OSRUN 
CUERY 
ZAP 


GLOBAL 
MACLIB 


MACLIB 


INCLUDE 
LOAD 
MACLIB 
TAPE 
TXTLIB 


GENMOD 
LOADMOD 
MODMAP 
NUCXLOAD 


NAMEFIND 
NAMES 


RECEIVE 
SENDFILE 


RECEIVE 
SENDFILE 


SYNONYS 


SCRIPT 


ASSEMBLE 
INCLUDE 
LOAD 
TXTLIB 


GLOBAL 
TXTLIB 


Comments 


Is a library created by the LKED command or 
the LOADLIB utility command. The GLOBAL or 
FILEDEF command identifies the libraries that 
should be searched for program execution. 
NUCXLOAD loads a member of a CMS LOADLIB 1li- 
brary or an OS module library. OSRUN executes 
a member of a CMS LOADLIB library or an OS 
module library. Query indicates the libraries 
that were affected by the GLOBAL command. ZAP 
is used to modify an existing LOADLIB member. 


Library members contain macro definitions or 
copy files; the MACLIB command creates the 

library, and lists, adds, deletes, or replaces| 
members. The GLOBAL command identifies which | 
macro libraries should be searched during an | 
assembly or compilation. 


Contains macro definitions to be added to a 
CMS macro library (MACLIB). 


Maps created by the LOAD and INCLUDE commands 
indicate entry point locations; the MACLIB, 
TXTLIB, and TAPE commands produce MAP files. 


MODULE files created by the GENMOD command are 
nonrelocatable executable programs. 

The LOADMOD commands loads a MODULE file for 
execution; the MODMAP command displays a map 
of entry point locations. NUCXLOAD loads a 
module into free storage and defines it as a 
nucleus extension. 


Contains information regarding users with 
whom you communicate. 


Contains records which log the transmission 
of files sent by or received by you. 


Contains notes sent to you or sent by you to 
to other users. 


Contains a table of synonyms for CMS commands 
and user—written EXEC and MODULE files. 


SCRIPT text processor input includes data and 
SCRIPT control words. 


TEXT files contain relocatable object code 
created by the assembler and compilers. The 
LOAD and INCLUDE commands load them into 
storage for execution. The TXTLIB command 
Manipulates libraries of TEXT files. 


Library members contain relocatable object 
code. The TXTLIB command creates the library, 
and lists or deletes existing members. The 
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Figure 3. Filetypes Used by CMS Commands (Part 2 of 3) 
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Command 


UPDATE 


UPDATE 


UPDATE 


ZAP 


Comments 


Contains UPDATE control statements for single 
updates applied to source programs. 
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Contains UPDATE control statements for 
Bultilevel updates. 


Contains control records for the ZAP command, 
which is used by system support personnel. 
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Comments 


When the SSERV command copies books or macros 
from DOS source statement libraries, the output 
is written to CMS COPY files, which can be added 
to CMS macro libraries with the MACLIB command. 


DOS core image phases are placed in a DOSLIB by 
linkage editor, invoked with the DOSLNK command. 
The GLOBAL command identifies DOSLIBs to be 
searched when the FETCH command is executed. 


Contains linkage editor control statements for 
input to the CMS/DOS linkage editor. 


utility progran. 
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Listings contain processor output from the ESERV 
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The PSERV command copies procedures from DOS 
procedure libraries into CMS PROC files. 


Object decks created by the assembler or 
compilers are written into TEXT files. The RSERV 
command creates TEXT files from modules in DOS 
relocatable libraries. TEXT files can also be 
used as input to the linkage editor. 


| SS EE a a a a a | 
Figure 4. Filetypes Used in CMS/DOS 
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OUTPUT FILES: TEXT AND LISTING 


Output files from the assembler and the language processors are 
logically related to the source programs by their filenanes. Some of 
these files are permanent and some are temporary. For example, if you 
issue the command: 


assemble mnyfile 


CMS locates a file named MYFILE with a filetype of ASSEMBLE and the 
system assembler assembles it. If the file is on your A-disk, then when 
the assembler completes execution, the permanent files you have are: 


MYFILE ASSEMBLE Al 

MYFILE TEXT Al 

MYFILE LISTING Al where the TEXT file contains the object code 
resulting from the assembly, and the LISTING file contains the program 
listing generated by the assembly. If any TEXT or LISTING file with the 
Same name previously existed, it is erased. The source input file, 
MYFILE ASSEMBLE Al, is neither erased nor changed. 


The characteristics of the TEXT and LISTING files produced by the 
assembler are the same as those created by other processors and programs 
in CMS. 


Because these files are CMS files, you can use the CMS’ editor to 
examine or modify their contents. If you want a printed copy of a 
LISTING file, you can use the PRINT command to print it. If you want to 
examine a TEXT file, you can use the TYPE or PRINT command specifying 
the HEX option. 


Note that if a TEXT file contains control changes for the terminal, 
the edit lines may not be displayed in their true form. Therefore, it 
is suggested you do not use the editor for TEXT files, because the 
results are unpredictable. Instead, use the TYPE or PRINT commands with 
the HEX option to display TEXT decks. Put TEXT decks into a TXTLIB and 
ZAP the TXTLIB to modify the TEXT deck. 


FILETYPES FOR TEMPORARY FILES 


The filetypes of files created by the assembler and language processors 
for use as temporary workfiles are; 


SYSUT1 SY¥S001 SY¥SO0OO0O4 
SYSUT2 SY¥S002 SY¥SO005 
SYSUT3 SYS003 SY¥S006 
SYSUT4 


CMS handles all SYSUTx and SYSOOx files as temporary files. 


The CMS AMSERV command, executing VSAM utility functions, uses two 
workfiles that have filetypes of LDTFDI1 and LDTFDI2. 


Disk space is allocated for temporary files on an as-needed basis. 
They are erased when processing is complete. If a program you are 
executing is terminated before completion, these workfiles May remain on 
your disk. You can erase then. 
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CMSUT1 Files 


The CMSUT1 filetype is used by CMS commands that create files on your 
CMS disks. The CMSUT1 file is used as a workfile and is erased when the 
file is created. When a command fails to complete execution properly, 
the CMSUT1 file may not be erased. CMSUT1 files are reserved for system 
usage, and use of these files may cause unpredictable results. The 
commands, and the filenames they assign to files they create, are listed 
below. 


Command Filename Command Filenane 

COPYFILE COPYFILE MACLIB DMSLBM 

DISK LOAD DISK READCARD READCARD 

EDIT EDIT TAPE LOAD TAPE 

INCLUDE DMSLDR UPDATE fn (the filename of 
LOAD DMSLDR the UPDATE file) 


FILETYPES FOR DOCUMENTATION 


There are two CMS reserved filetypes for which the CMS Editor and System 
Product Editor accept (by default) uppercase and lowercase input data. 
These are MEMO and SCRIPT. You can use MEMO files to document program 
notes or to write reports. The SCRIPT filetype is used by the SCRIPT or 
SCRIPTVS commands. These commands invoke text processors that are IBM 
Installed User Program (IUP) and IBM program products, respectively. 


Filemode Letters and Numbers 


The filemode field of acCMS file identifier has two characters: the 
filemode letter and the filemode number. The filemode letter is 
established by the ACCESS command and specifies the virtual disk on 
which a file resides: A through Z. The filemode number is a number from 
0 to 5, which you can assign to the file when you create it or rename 
it; if you do not specify it, the value defaults to 1. How you access 
your disks and what filemode letters you give them with the ACCESS 
command depends on how you want to use the files that are on then. 


For most of the reading and writing you do of files, you’ use your 
A-disk, which is also known as your primary disk. This is a read/write 
disk. You may access other disks in your configuration, or access 
linked-to disks, in read-only or read/write status, depending on whether 
you have a read-only or read/write link. 


When you load CMS (with the IPL command), your virtual disk at 
address 191 is accessed for you as your A-disk. Your virtual disk at 
address 190 (the system disk) is accessed as your S-disk; and the disk 
at 19E is accessed as an extension of your S-disk, with a mode letter of 
Y. The S-disk and Y-disk are accessed for only mode S2 and Y2 files, 
thus: 


access 190 S * * S§2 
access 19EF Y * * Y2 


In addition, if you have a disk defined at address 192, it is accessed 
for you as your D-disk. If the 192 disk has not been formatted, CMS 
will do it automatically and label the minidisk 'SCRTCH'. 

If ACCESS is the first command issued after an IPL of the CMS systen, 
only the A-disk is not automatically defined. Another ACCESS command 
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Rust be issued to define the A-disk. 


The actual letters you assign to any other disks (and you may 
reassign the letters A, D, and Y), is arbitrary; but it does determine 
the CMS search order, which is the order in which CMS’ searches your 
disks when it is looking for a file. The order of search (when all disks 
are being searched) is alphabetical: A through Z. If you have duplicate 
file identifiers on different disks, you should check your disk search 
order before issuing commands against that filename to be sure that you 
will get the file you want. You can find out the current search order 
for your virtual disks by issuing the command: 


query search 
You can also access disks as logical extensions of other disks, for 
example: 
access 235 b/a 
The "/A" indicates that the B-disk is to be a read-only extension of the 
A-disk, and the A-disk is considered the "parent" of the B-disk. A disk 


may have many extensions, but only one level of extension is allowed. 
If you access an extension A-disk containing no files, the access fails. 


How Extensions Are Used 


ome 


If you have a disk accessed as anextension of another disk, the 
extension disk is automatically read-only, and you cannot write on it. 
You might access a disk as itS own extension, therefore, to protect the 
files on it, so that you do not accidentally write on it. For example: 


access 235 b/b 


Another use of extensions is to extend the CMS search order. If you 
issue a command requesting to read a file, for example: 


type alpha plan 


CMS searches your A-disk for the file named ALPHA PLAN and if it does 
not find it, searches any extensions that your A-disk may have. If you 
have a file named ALPHA PLAN on your B-disk but have not accessed it as 
an extension of your A-disk, CMS will not find the file, and you will 
have to reenter the command: 


type alpha plan b 


Additionally, if you issue a CMS command that reads and writes a 
file, and the file to be read is on an extension of a read/write disk, 
the output file is written to the parent read/write disk. The EDIT 
command is a good example of this type of command. If you have a file 
named FINAL LIST on a B-disk extension of a read/write A-disk, and if 
you invoke the editor to modify the file with the command: 


edit final list 


after you have made modifications to the file, the changed file is 
written onto your A-disk. The file on the B-disk remains unchanged. 
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Accessing and Releasing Read-Only Extensions 


When you access a disk as a read-only extension, it remains an extension 
of the parent disk as long as both disks are still accessed. If either 
disk is released, the relationship of parent disk/fextension is 
terminated. 


If the parent disk is released, the extension remains accessed and 
you may still read files on it. If you access another disk at the mode 
letter of the original parent disk, the parent/extension relationship 
remains in effect. 


If you release a read-only extension and access another disk with the 
same mode letter, it is not an extension of the original parent disk 
unless you access it as such. For example, if you enter: 


access 198 C/fa 
release c 
access 199 c 


the C-disk at virtual address 199 is not an extension of your A-disk. 


WHEN TO SPECIFY FILEMODE LETTERS: READING FILES 


When you request CMS to access a file, you have to identify it so that 
CMS can locate it for you. The commands that expect files of particular 
filetypes (reserved filetypes) allow you to enter only the filename of 
the file when you issue the command. When you execute any of these 
commands or execute a MODULE or EXEC file, CMS searches all of your 
accessed disks (using the standard search order) to locate the file. 
The CMS commands that perform this type of search are: 


AMSERV GLOBAL MODMAP 
ASSEMBLE LOAD RUN 
DOSLIB LOADMOD TXTLIB 
EXEC MACLIB 


Some CMS commands require you to enter the filename and filetype to 
identify a file. You may specify the filemode letter; if you do not 
specify the filemode, CMS searches only your A-disk and its extensions 
when it looks for the file. If you do specify a filemode letter, the 
disk you specify and its extensions are searched for the file. fhe 
commands you use this way are: 


EDIT PUNCH TAPE DUMP 
ERASE STATE TYPE 
FILEDEF SYNONYM UPDATE 
PRINT 


There are three CMS commands that do not search extensions of disks 
when looking for files. They are: 


DISK DUMP 
FILELIST 
LISTFILE 


You must explicitly enter the filemode if you want to use these commands 
to list or dump files that are on extensions. 


The following commands search every accessed read-only and read-write 
disk. 
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NAMES 
NAMEFIND 


Using Asterisks and Equal Signs 


For some CMS commands, if you specify the filemode of a file as an 
asterisk, it indicates that you either do not know or do not care what 
disk the file is on and you want CMS to locate it for you. For example, 
if you enter: 


listfile mnyfile test * 


the LISTFILE command responds by listing all files on your accessed 
disks named MYFILE TEST. When you specify an asterisk for the filemode 
of the COPYFILE, ERASE, or RENAME commands, CMS locates all copies of 
the specified file. For example: 


rename temp sort * good sort = 


renames all files named TEMP SORT to GOOD SORT on all of your accessed 
read/write disks. An equal sign (=) is valid in output fileids for the 
RENAME and COPYFILE commands. 


For some commands, when you specify an asterisk for the filemode of a 
file, CMS stops searching as soon as it finds the first copy of the 
file. For example: 


type myfile assemble * 
If there are files named MYFILE ASSEMBLE on your A-disk and C-disk, then 


only the copy on your A-disk is displayed. The commands that perforn 
this type of search are: 


COMPARE PRINT STATE 
DISK DUMP PUNCH SYNONYSA 
EDIT RUN TAPE DUMP 
FILEDEF SORT TYPE 


For the COMPARE, COPYFILE, RENAME, and SORT commands, you must always 
specify a filemode letter, even if it is specified as an asterisk. 


WHEN TO SPECIFY FILEMODE LETTERS: WRITING FILES 


When you issue a CMS command that writes a file onto one of your virtual 
disks, and you specify the output filemode, CMS writes the file onto 
that disk. The commands that require you to specify the output filemode 
are: 


COPYFILE 
RENAME 
SORT 


The commands that allow you to specify the output filemode, but do 
not require it, are: 


FILEDEF TAPE LOAD 
GENMOD TAPPDS 
READCARD UPDATE 


When you do not specify the filemode on these commands, CMS writes the 
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output files onto your A-disk. 


Some CMS commands that create files always write them onto your 
A-disk. The LOAD and INCLUDE commands write a file named LOAD MAP A5. 
The LISTFILE command creates a file named CMS EXEC, on your A-disk. The 
CMS/DOS commands DSERV, ESERV, SSERV, PSERV, and RSERV also write files 
onto your A-disk. 


Other commands that do not allow you to specify the filemode, write 
output files either: 


e To the disk from which the input file was read, or 
® To your A-disk, if the file was read from a read-only disk 


These commands are: 


AMSERV 
MACLIB 
TXTLIB 
UPDATE 


The SORT command also functions this way if you specify the output 
filemode as an asterisk (*). 


In addition, many of the language processors, when creating work 
files and permanent files, write onto the first read/write disk in your 
search order, if they cannot write on the source file's disk or its 
parent. 


HOW FILEMODE NUMBERS ARE USED 


Whenever you specify a filemode letter to reference a file, you can also 
specify a filemode number. Since a filemode number for most of your 
files is 1, you do not need to’ specify it. The filemode numbers 0, 2, 
3, 4, and 5 are discussed below. Filemode numbers 6 through 9 are 
reserved for IBM use. 


Filemode 0: A filemode number of 0 assigned to a file makes that file 
private. No other user may access it unless they have read/write access 
to your disk. Under normal circumstances; if someone links to your disk 
in read-only mode and requests a list of all the files on your disk, the 
files with a filemode of 0 are not listed. 


The DDR command will allow you to copy the minidisk from one disk to 
another, and therefore, the filemode 0 files. Use a read _ share 
password to protect minidisks with private files when using ACCESS. 


Filemode 2: Filemode 2 is essentially the same, for the purposes of 
reading and writing files, as filemode 1. Usually a filemode of 2 is 
assigned to files that are shared by users who link to a common disk, 
like the system disk. Since you can access a disk and specify which 
files on that disk you want to access, files with a filemode of 2 
provide a convenient subset of all files on a disk. For example, if you 
issue the command: 


access 489 e/a * * e2 


you can only read files with a filemode of 2 on the disk at virtual 
address 489. 
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Filemode 3: Files with a filemode of 3 are erased after they are read. 
If you create a file with a filemode of 3 and then request that it be 
printed, the file is printed, and then erased. You can use this filemode 
if you write a program or EXEC procedure that creates files that you do 
not want to maintain copies of on your virtual disks. You can create the 
file, print it, and not have to worry about erasing it later. 


The language processors and some CMS commands create work files and 
give these work files a filemode of 3. 


Note: A filemode of 3 should not be used with EXECs. Depending on what 
commands are issued within it, an EXEC with a filemode of 3 may be 
erased before it completes execution. 


Filemode 4: Files with a filemode of 4 are in OS simulated data set 
format. These files are created by OS macros in programs running in 
CMS. You specify that a file created by a program is to have OS 
Simulated data set format by specifying a filemode of 4 when you issue 
the FILEDEF command for the output file. If you do not specify a 
filemode of 4, the output file is created in CMS format. 


You can find more details about OS simulated data sets in "Section 8. 
Developing OS Programs Under CMS." 


Note: There are no filemode numbers reserved for DOS or VSAM data sets, 
Since CMS does not simulate these file organizations. 


Filemode 5: This filemode number is the same, for purposes of reading 
and writing, as filemode 1. You can assign a filemode of 5 to files that 
you want to maintain as logical groups, so that you can manipulate then 
in groups. For example, you can reserve the filemode of 5 for all files 
that you are retaining for a certain period of time; then, when you want 
to erase them, you could issue the command: 


erase * * a5 


When To Enter Filemo 
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You can assign filemode numbers when you use the following commands: 


COPYFILE: You can assign a filemode number when you create a new file 
With the COPYFILE command. 


EDIT: You can asSign a filemode number when you create a file with the 
CMS editor. To change the filemode number of an existing file, use the 
RENAMB or COPYFILE commands, or use the FMODE subcommand when you are in 
the edit environment. 


DLBL, FILEDEF: When you assign file definitions to disk files for 
programs or CMS command functions, you can specify a filemode number. 


GENMNQD: You can specify a filemode number on the GENMOD command line. 
To change the filemode number of an existing MODULE file, use the RENAME 
or COPYFILE commands. 


READCARD: You can assign a filemode number when you specify a_ file 
identifier on the READCARD command line or on a READ control card. 


RENAME: When you specify the fileids on the RENAME command, you can 
specify the filemode numbers for the input and/or output files. To 
change only the filemode number of an existing file, you must’ use the 
RENAME option. For example: 
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RENAME test module al = = a2 
changes the filemode number of the file TEST MODULE A from 1 to 2. 


: You can specify filemode numbers for the input and/or output 
fileids on the SORT command line. 


Managing Your CMS Disks 


The number of files you can write on a CMS disk depends on both the size 
of the disk and the size of the files that it contains. You can find 
out how much space is being used ona disk by using the QUERY DISK 
command. For example, to see how much space iS on your A-disk, you would 
enter: 


query disk a 


The response may be something like this: 


LABEL cuu M STAT CYL TYPE BLKSIZE FILES BLKS USED-(%) BLKS LEFT BLK TOTAL 
MYDISK 191 A R/W 5 3330 1024 171 1221-92 107 1328 


When a disk is becoming full, you should erase whatever files you no 
longer need. Or dump to tape files that you need to keep but do not need 
to keep active on disk. 


When you are executing a command or program that writes a file to 
disk, and the disk becomes full in the process, you receive an error 
message, and you have to try to clear some space on the disk before you 


can attempt to execute the command or program again. To avoid the 
delays that such situations cause, you should try to maintain an 
awareness of the usage of your disks. If you cannot erase any nore 


files from your disks, you should contact installation support personnel 
about obtaining additional read/write CMS disk space. 


CMS File Directories 


Each CMS disk has a master file directory that contains entries for each 
of the CMS files on the disk. When you access a disk, information fron 
the master file directory is brought into virtual storage and written 
into a user file directory. The user file directory has an entry for 
each file that you may access. If you have accessed a disk specifying 
only particular files, then the user file directory contains entries 
only for those files. 


If you have read/write access to a disk, then each time you write the 
file onto disk the user file directory and master file directory are 
updated to reflect the current status of the disk. If you have 
read/write access to a disk and the FSCLOSE macro is issued, the user 
file directory is updated. When there are no open files on the disk, 
the master file directory is updated to reflect the current status of 
the files. If you have read-only access to a disk, then you cannot 
update the master file directory or user file directory. If you access 
a read-only disk while another user is writing files onto it, you may 
need to periodically reissue the ACCESS command for the disk, to obtain 
a fresh copy of the master file directory. 
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Note: You should never attempt to write on a disk at the same time as 
another user. 


The user file directory remains in virtual storage until you issue 
the RELEASE command specifying the node letter or virtual address of the 
disk. If you detach a virtual disk (with the CP DETACH command) without 
releasing it, CMS does not know that the disk is no longer part of your 
virtual machine. When you attempt to read or write a file on the disk 
CMS assumes that the disk is still active (because the user file 
directory is still in storage) and encounters an error when it tries to 
read or write the file. 


A similar situation occurs if you detach a disk and then adda new 
disk to your virtual machine using the same virtual address as the disk 
you detached. For example, if you enter the following sequence of 
commands: 


cp link userl1 191 195 rr rpass! 
access 195 d 

cp detach 195 

cp link user2 193 195 rr rpass2! 
listfile * * d 


the LISTFILE command produces a list of the files on JUSER1's 191 disk; 
if you attempt to read one of these files, you receive an error message. 
You must issue the ACCESS command to obtain a copy of the master file 
directory for USER2's 193 disk. 


The entries in the master file directory are sorted alphamerically by 
filename and filetype, to facilitate the CMS search for particular 
files. When you are updating disk files, the entries in the user file 
directory and master file directory tend to become unsorted as files are 
created, updated, and erased. When you use the RELEASE command to 
release a read/write disk, the entries are sorted and the master file 
directory is rewritten. If you or any other user subsequently access 
the disk, the file search may be more efficient. 


CMS Command Search Order 


When you enter a command line in the CMS environment, CMS has to locate 
the command to execute. If you have EXEC or MODULE files on any of your 
accessed disks, CMS treats them as commands; also, they are known as 
user-written commands. 


AS soon as the command name is found, the search stops and the 
command is executed. The search order is: 


1. Search for a file with filetype EXEC on any currently accessed 
disk. CMS uses the standard search order (A through Z.) 


2. Search for a valid name on any currently accessed disk, according 
to current SYNONYM file definitions in effect. 


3. Search for a nucleus extension command if the high order byte of 
register 1 is not equal to X'03' or X'O4'. 


1Note that the password cannot be entered on the command line if the 
password suppression facility was specified at sysgen. 
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4. Search for a command in the transient area. Commands which may be 
in the transient area are: 


ACCESS HELP READCARD 
ASSGN LISTFILE RELEASE 
COMPARE MODMAP RENAME 
DISK. OPTION SET 

DLBL PRINT SVCTRACE 
FILEDEF PUNCH SYNONYSN 
GENDIRT QUERY TAPE 
GLOBAL RDR TYPE 


5S. Search for a nucleus-resident command. Some nucleus-resident CMS 
commands are: 


| CP | GENMOD | NAMEFIND 
| DEBUG [ INCLUDE | START 

| ERASE [ LOAD [ STATE 

[ EXECIO | LOADMOD | STATEW 

[ FETCH 


6. Search for a file with filetype MODULE on any currently accessed 
disk 


7. Search for a valid abbreviation or truncation of a nucleus 
extension. 


8. Search for a valid abbreviation or truncation of a command in the 
transient area. 


9. Search for a valid abbreviaticn or truncation of a command in the 
nucleus. 


10. Search for a valid abbreviation or truncation of any other CMS 
command 


11. Search for a CP command. 
12. Search for a valid abbreviation or truncation of a CP command. 

For example, if you create a command module that has the same name as 
a CMS nucleus-resident command, your command module cannot be executed, 
Since CMS locates the nucleus-resident command first, and executes it. 
When a user-written command has the same name as a CMS command nodule 
abbreviation, certain error messages gay indicate the CMS command nane, 
rather than the program name. 


Figure 5 illustrates details of the command search order. 
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How CMS Searches for the Command to Execute 
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EXECUTE 
THE FILE 


AND RETURN 
CONTROL TO 
CMS. 


EXPAND THE 
NAME TO THE 
FULL REAL 
NAME, EXECUTE 
IT, AND RETURN 
CONTROL TO CMS. 


EXECUTE THE 
NUCLEUS EXTENSION 
AND RETURN CONTROL 
TO CMS. 


EXECUTE THE 
FILE AND 

RETURN CONTROL 
TO CMS. 


EXECUTE THE MODULE 
AND RETURN CONTROL 
TO CMS. 


EXECUTE THE FILE 
AND RETURN CONTROL 
TO CMS. 


EXPAND THE NAME 
TO THE FULL REAL 
NAME, EXECUTE IT, 
AND RETURN 
CONTROL TO CMS. 


EXPAND THE 

NAME TO THE FULL 
REAL NAME, EXECUTE 
IT, AND RETURN 
CONTROL TO CMS. 


EXECUTE THE COMMAND 
AND RETURN CONTROL 
TO CMS. 


Section 5. The Editors 


In CMS usage, the term edit is used in a variety of ways, all of which 
refer, ultimately, to the functions of the CMS Editor or the Systen 
Product Editor. 


When you issue the EDIT command, the System Product Editor 
automatically places you in CMS Editor (EDIT) compatibility mode. In 
this mode, you can issue both EDIT and XEDIT subcommands. For complete 
information on EDIT compatibility mode, as well as instructions on how 
to invoke the System Product Editor, see the VM/SP System Product Editor 
Command and Macro Reference. 


The CMS Editor 


To edit a file means to make changes, additions, or deletions to a CMS 
file that is on a disk, and to make these changes interactively: you 
instruct the editor to make a change, the editor does it, and then you 
request another change. 


You can edit a file that does not exist; when you do so, you create 
the file online, and can modify it as you enter it. 


To file a file means to write a file you are editing back ontoa 
disk, incorporating any changes you made during the editing session. 
When you issue the FILE subcommand to write a file, you are no longer in 
the environment of the CMS Editor, but are returned to the CMS 
environment. You can, however, write a file to disk and then continue 
editing it, by using the SAVE subcommand. 


An editing session is the period of time during which a file is in 
your virtual storage area, from the moment you issue the EDIT command 


and the editor responds EDIT: until you issue the FILE or QuvIT 
subcommands to return to the CMS command environment. 


The EDIT Command 


When you issue the EDIT command you must specify the filename and 
filetype of the file you want to edit. If you issue: 


edit test file 
CMS searches your A-disk and its extensions for a file with the 
identification TEST FILE. If the file is not found, CMS assumes that you 
want to create the file and issues the message: 


NEW FILE: 
EDIT: 


to inform you that the file does not already exist. 
If the file exists on a disk other than your. A-disk and its 
extensions, or if you want to create a file to write on a read/write 


disk other than your A-disk, you must specify the filemode of the file: 


edit test file b 
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In this example, your B-disk and its extensions are searched for the 
file TEST FILE. 


After you issue the EDIT command, you are in edit mode, or the 
environment of the CMS editor. If you have specified the filename and 
filetype of a file that already exists, you can now use EDIT subcommands 
to make changes or corrections to lines in that file. If you want to 
add records to the file, as you would if you are creating a new file, 
issue the EDIT subcommand: 


input 


to enter input mode. Every line that you enter is considered a data line 
to be written into the disk file. For most filetypes, the editor 
translates all of your input data to uppercase characters, regardless of 
how you enter it. For example, if you create a file and enter input 
mode as follows: 


edit myfile test 

NEW FILE: 

EDIT: 

input 

INPUT: 

This is a file I an 

learning to create with the CMS editor. 


the lines are written into the file as: 


THIS IS A FILE I AM 
LEARNING TO CREATE WITH THE CMS EDITOR. 


You can use the VMN/SP logical line editing symbols to modify data 
lines as you enter then. 


To return to edit mode to modify a file or to terminate the edit 
session, you must press the Return key on a null line. If you have just 
entered a data line, for example, and your terminal's typing element or 
cursor is positioned at the last character you entered, you must press 
the Return key once to enter the data line, and a second time to enter a 
null line. 


You may also use the logical line end symbol to enter a null line; 
for example: 


last line of input# 
# 


Both of these lines cause you to return to edit mode from input mode. 


If you do not enter a null line, kLut enter an EDIT subcommand or CMS 
command, the command line is written into your file as input. The only 
exception to this is a line that begins with the characters &#CP. These 
characters indicate that the command is to be passed igmediately to CP 
for processing. 


WRITING A FILE ONTO DISK 


A file you create and the modifications that you make to it during an 
edit session are not automatically written to a disk file. To save the 
results, you can do the following: 
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e Periodically issue the subcommand: 
save 


to write onto disk the contents of the file as it exists when you 
issue the subcommand. Periodically issuing this EDIT subcommand 
protects your data against a system failure; you can be’ sure that 
changes you make are not lost. 


e At the beginning of the edit session, issue the AUTOSAVE subcomnand, 
with a number: 


autosave 10 


Then, for every tenth change or addition to the file, the editor 
issues an automatic save request, which writes the file onto disk. 


e At the end of the edit session, issue the subconmand: 
file 


This subcommand terminates the CMS Editor session, writes the file 
onto disk, replacing a previous file by that name (if one existed), 
and returns you to the CMS environment. You can return to the edit 
environment by issuing the EDIT command, specifying a different file 
or the same file. 


The editor decides which disk to write the file onto according to the 
following hierarchy: 


e If you specify a filemode on the FILE or SAVE subcommand line, the 
file is written onto the specified disk. 


e If the current filemode of the file is the mode of a read/write disk, 
the file is written onto that disk. (If you have not specified a 
filemode letter, it defaults to your A-disk.) 


e If the filemode is the mode of a read-only extension of a read/write 
disk, the file is written onto the read/write parent disk. 


e If the filemode is the mode of a read-only disk that is not an 
extension of a read/write disk, the editor cannot write the file and 
issues an error message. 


See "Changing File Identifiers" for information on how you can tell 
the editor what disk to use when writing a file. 


If you are editing a file and decide, after making several changes, 
that you do not wish to save the changes, you can use the subcommand: 


quit 


No changes that you made since you last used the SAVE subcommand (or the 
editor last issued an automatic save for you) are retained. If you have 
just begun an edit session, and have made no changes at all toa file, 
and for some reason you do not want to edit it at all (for example, you 
misspelled the name, or want to change a CMS setting before editing the 
file), you can use the QUIT subcommand instead of the FILE subcommand to 
terminate the edit session and return to CMS. 


A file must have at least one line of data in order to be written. 
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EDIT SUBCOMMANDS 


While you are in the edit environment, you can issue any EDIT subcommand 
Or macro. An edit macro is an EXEC file that contains a sequence of EDIT 
Subcommands that execute as a unit. You can create your own EDIT 
subcommands with the CMS EXEC facility. EDIT subcommands provide a 
variety of functions. You can: 


e Position the current line pointer at a particular line, or record, in 
a file. 

e Control which columns of a file are displayed or searched during an 
editing session. 


e Modify data lines. 


e Describe the characteristics that a file and its individual records 
will have. 


e Automatically write and update sequence numbers for fixed-length 
records. 


e Edit files by line number. 


e Control the editing session. 


Like CMS commands, EDIT subcommands have a subcommand name and some have 
operands. In most cases, a subccmmand name (or its truncation) can be 
separated from its operands by one or more blanks, or no blanks. For 
example, the subcommand lines: 


are eguivalent. 
Several subcommands also use delimiters, which enclose a character 


string that you want the editor to operate on. For example, the CHANGE 
Ssubcommand can be entered: 


change/apple/pear/ 
The diagonal (/) delimits the character strings APPLE and PEAR. For the 
subcommands CHANGE, LOCATE, and DSTRING, the first nonblank character 
following the subcommand name (or its truncation) is considered the 
delimiter. No blank is required following the subcommand name. In the 
subcommand: 

locate $vm/$ 


the dollar sign (%$) is the delimiter. You cannot use a / in this case, 
since the diagonal is part of the character string you want to locate. 


When you enter these subcommands, you may omit the final delimiter; 
for examplé: 


dstring/csect 
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You must enter the final delimiter, however, when you specify a global 
change with the CHANGE subcommand. 


For the FIND and OVERLAY subcommands, additional blanks following the 
subcommand names are interpreted as arguments. The subcommand: 


find Pudding 


requests the editor to locate the line that has " Pudding" in columns 1 
through 9. Initial blanks are considered part of the character string. 


An asterisk, when used with an EDIT subcommand, may mean "to the end 
of the file" or "to the record length." For example: 


delete* 
deletes all of the lines in a file, beginning with the current line. 
verify * 


indicates that the editor should display the entire length of records. 


When you make an error entering an EDIT subcommand, the editor displays 
the message: 


PEDIT: line... 


where line... is the line, as you entered it, that the editor does not 
understand. 


The Current Line Pointer 


When you begin an editing session, a file is copied into virtual 
storage; in the case of a new file, virtual storage is acquired for the 
file you are creating. In either case, you can picture the file as a 
series of records, or lines; these lines are available to you, one at a 
time, for you to modify or delete. You can also insert new lines or 
records following any line that is already in the file. 


The line that you are currently editing is pointed to by the current 
line pointer. On a display terminal, this line is highlighted. 


What you do during an editing session is: 


e Position the current line pointer to access the line you want to 
edit. 


e Edit the line: change character strings in it, delete it or insert 
new records following it. 


e Position the line pointer at the next line you want to edit. 


When you are editing a file and you issue an EDIT subcommand that 
either changes the position of the line pointer or that changes a line, 
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the current line or the changed line (or lines) is displayed. You can 
also display the current line by using the TYPE subcommand: 


type 


If you want to examine more than one line in your file, you can use the 
TYPE subcommand with a numeric parameter. If you enter: 


type 10 


the current line and the nine lines that follow it are displayed; the 
line pointer then stays positioned at the last line that was displayed. 


You can move the line pointer up or down in your file. “Up" indicates 
a location toward the beginning of the file (the first record); "down" 
indicates a location toward the end of the file (the last record). You 


use the EDIT subcommands UP and DOWN to move the line pointer up or down 
one or more lines. For example: 


up 5 


moves the current line pointer toa line five lines closer to the 
beginning of the file, and: 


down 
moves the pointer to point at the next sequential record in the file. 
You can also request that the line pointer be placed at _ the 
beginning, or top of the file, or at the end, or bottom of the file. 
When you issue the subcommand: 
top 
you receive the message: 
TOF: 
and the line pointer is positioned at a null line that is always at the 
top of the file. This null line exists only during your editing session; 
it is not filed on disk when you end the editing session. 
When you issue the subcommand: 
botton 
the current line pointer is positioned at the last record in the file. 
If you now enter input mode, all lines that you enter are appended to 


the end of the file. 


If the current line pointer is at the bottom of the file and you 
issue the DOWN subcommand, you receive the message: 


EOF: 


and the current line pointer is positioned at the end of file, following 
the last record. 


When you are adding records to your file, the current line pointer is 
always pointing at the line you last entered. When you delete a line 
from a file, the line pointer moves down to point to the next line down 
in the file. 
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Going from edit mode to input mode does not change the current line 
pointer. If you are creating a new file and, every 30 lines or so, you 
move the current line pointer to make corrections to the lines that you 
have entered, you must issue the BOTTOM subcommand to begin entering 
more lines at the end of the file. 


The current line pointer is also moved as the result of the LOCATE 
and FIND subcommands. You use the FIND subcommand to get to a line when 
you know the characters at the beginning of the line. For example, if 
you want to change the line: 


BAXTER JF. 065941 ACCNINT 
you could first locate it by using the subcommand: 
find baxter 


If you do not know the first characters on a line, you can issue the 
LOCATE subcommand: 


locate /accntnt/ 


Both of these subcommands work only in a top-to-bottom direction: you 
cannot use them to position the line pointer above the current line. If 
you use the FIND or LOCATE subcommands and the target (the character 
string you seek) is not found, the editor displays a message, and 
positions the line pointer at the end of the file. Subseguently, if you 
reissue the subcommand, the editor starts searching at the top of the 
file. 


In a situation like that above, or in a case where you are 
repetitively entering the same LOCATE or FIND subcommand (if, for 
example, there are many occurrences of the same character string, but 
you seek a particular occurrence) you can use the = (REUSE) subcommand. 
To use the example above, you are looking for a line that contains the 
string ONCE UPON A TIME, but you do not know that it is above the 
current line. When you issue the subcommand: 


locate /fonce upon a time/ 
the editor does not locate the line, and responds: 


NOT FOUND 
EOF: 


If you enter: 


the editor searches again for the same string, beginning this time at 
the top of the file, and locates the line; 


“ONCE UPON A TIME" IS A COMMON 


This may still not be the line you are looking for. You can, again, 
enter: 


The LOCATE subcommand is executed again. This time, the editor might 
locate the line: 


A STORY THAT STARTED ONCE UPON A TIME 
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Figure 6 illustrates a simple CMS file, and indicates how the current 
line pointer would be positioned following a sequence of EDIT 
subcommands. 


LINE-NUMBER EDITING: Some fixed-length files are suitable for editing by 
referencing line numbers instead of character strings. The EDIT 
subcommands that allow you to change the line pointer position by line 
number are discussed under "Line~Number Editing." 


EDIT PPRINT EXEC 
CLP 


! 

1 

! 
Vv 


TOF: 

(null line) 

&CONTROL OFF 

&P = 

SIF .&61 EQ . &EXIT 100 
&FN = &1 

&6IF &1 EQ ? &GOTO -TELL 
&NPN = &CONCAT §$ &1 

SIF .&62 EQ .« &EXIT 200 
&FT = &2 

EFM = &3 

10 &IF .&3 NE . &SKIP 2 

11 SFM = A 

12 &SKIP 3 

13 &IF &3 NE ( &SKIP 2 

14 &FM = A 

15 EP = ( 

16 &CONTROL ALL 

17 COPY &FN &FT &FM ENFN SFT A ( UNPACK 


WwOANNUWE WN = © 


PRINT ENFN SFT A &P 6&4 &5 &6 &7 &8 &9 &10 &11 &12 £613 &14 

19 ERASE &NFN &FT A 

21 -TELL &TYPE THIS EXEC PRINTS A LISTING FROM PACKED FORMAT 
EOF: 


The line numbers represented are symbolic: they are not an actual 
part of the file, but are used below to indicate at which line the 
current line pointer is positioned after execution of the EDIT 
subcommand indicated. 
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Subcomnmand CLP Position 

---- ---> 0 

DOWN 5 ==——> 5 

UP ---> 4 

LOCATE /UNP/ ---> 17 

TYPE 3 ---> 19 

BOTTOM =aa> 21 

DOWN =-=> EOF: 

FIND - ===> 21 

TOP ---> 0 

CHANGE /EQ/EQ/ 6 ==>) 25 

DELETE 2 ---> 7 (lines numbered 5 and 6 are deleted) 
INPUT * ---> the line just entered (between 7 and 8) 


a a ee 
Figure 6. Positioning the Current Line Pointer 
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Verification and Search Columns 


There are two EDIT subcommands you can use to control what you and the 
editor "see" ina file. The VERIFY subcommand controls what you see 
displayed; the ZONE subcommand controls what columns the editor 
searches. Normally, when you edit a file, every request that you make 
of the editor results in the display of one or more lines at your 
terminal. If you do not want to see the lines, you can specify: 


verify off 


Alternatively, if you want to see only particular columns ina file, you 
can specify the columns you wish to have displayed: 


verify 1 30 


Some filetypes have default values set for verification, which 
usually include those columns in the file that contain text or data, and 
exclude columns that contain seguence numbers. If a verification column 
is less than the record length, you can specify: 


verify * 
to indicate that you want to see all columns displayed. 


In conjunction with the VERIFY subcommand, you can use the ZONE 
subcommand to tell the editor within which columns it can search or 
modify data. When you issue the subcommand: 


zone 20 30 


The editor ignores all text in columns 1-19 and 31 to the end of the 
record when it searches lines for LOCATE, CHANGE, ALTER, and FIND 
subcommands. You cannot unintentionally modify data outside of these 
fields; you must change the zones in order to operate on any other data. 


The zone setting also controls the truncation column for records when 
you are using the CHANGE subcommand; for more details, see "Setting 
Truncation Limits." 


Changing, Deleting, and Adding Lines 


You can change character strings in individual lines of data with the 
CHANGE subcommand. A character string may be any length, or it may be a 
null string. Any of the characters on your terminal keyboard, including 
blanks, are valid characters. The following example shows a simple data 
line and the cumulative effect of CHANGE subcomnmands. 


ABC ABC ABC 
is the initial data line. 


CHANGE /ABC/XYZ/ 
changes the first occurrence of the character string "ABC" to the 
string "XYZ". 
XYZ ABC ABC 

CHANGE /ABC// 
deletes the character string "ABC" and concatenates the characters 
On each side of it. 


XY¥Z ABC 
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CHANGE //ABC/ 
inserts the string "ABC" at the beginning of the line. 


ABCXYZ ABC 


CHANGE /XYZ /XYZ/ 
deletes one blank character following "XYZ". 


ABCXYZ ABC 


CHANGE /C/C / 
adds a blank following the first occurrence of the character "C",. 


ABC XY¥Z ABC 

is the final line. 
THE ALTER SUBCOMMAND: You can use the ALTER subcommand to change a 
Single character; the ALTER subcommand allows you to specify a 
hexadecimal value so that you can include characters in your files for 
which there are no keyboard equivalents. Once in your file, these 
characters appear during editing as nonprintable blanks. For example, 
if you input the line: 

IF A = B THEN 
in edit mode and then issue the subcommand: 

alter = 8c 
the line is displayed: 


IF A B THEN 


If you subsequently print the file containing this line on a printer 
equipped to handle special characters, the line appears as: 


IF A < B THEN 
Since X'8C' is the hexadecimal value of the special character <. 

Either or both of the operands on the ALTER subcommand can be 
hexadecimal or character values. To change the xX*'8C* to another 
character, for example <, you could issue either: 

alter 8c ae 

alter 8c < 
THE OVERLAY SUBCOMMAND: The OVERLAY subcommand allows you’ to replace 
characters in a line by spacing the terminal's typing element or cursor 
to a particular character position to make character-for-character 
replacements, or overlays. For example, given the line: 

ABCDEF 
the subcommand: 

overlay xyz 


results in the line: 


XYZDEF 
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A blank entered on an OVERLAY line indicates that the corresponding 
character is not to he changed; to replace a character with a blank, use 
an underscore character (_). Given the above line, XYZDEF, the 
subcommand: 


overlay 3 
results in: 


DE3 (The "D" is preceded by blanks in columns 1, 2, and 3.) 


Global Changes 


You can make global or repetitive changes with the CHANGE and ALTER 
subcommands. On these subcommand lines, you can include operands that 
indicate: 


e The number of lines to be searched for a character or character 
string. An asterisk (*) indicates that all lines, from the current 
line to the end of the file, are to be searched. 


e Whether only the first occurrence or all occurrences on each line are 
to be modified. An asterisk (*) indicates all occurrences. If you do 
not specify an asterisk, only the first occurrence on any line is 
changed. 


For example, if you are creating a file that uses the (e) special 
character (X'AF"') and you do not want to use the ALTER subcommand each 
time you need to enter thee, you could use the character - as a 
Substitute each time you need to enter a @. When you are finished 
entering input, move the current line pointer to the top of the file, 
and issue the global ALTER subconmand: 


top#alter =~ af * * 


All occurrences of the character ~ are changed to X'*AF*. The current 
line pointer is positioned at the end of the file. 


When you use a global CHANGE subcommand, you must be sure to use the 
final delimiter on the subcommand line. For example: 


change /hannible/hannibal/ 5 


This subcommand changes the first occurrence of the string "HANNIBLE" on 
the current line and the four lines immediately following it. 


You can also make global changes with the OVERLAY subcommand, by 
issuing a REPEAT subcommand just prior to the OVERLAY subcommand. Use 
the REPEAT subcommand to indicate how many lines you want to be 
affected. For example, if you are editing a file containing the three 
lines: 


QO wo > 


with the current line pointer at line "A", issuing the subcommands: 


repeat 3 
overlay I | | 
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results in: 


The current line pointer is now positioned at the line beginning with 
the character "Cc", 


Deleting Lines 


You delete lines from a file with the DELETE subcommand; to delete nore 
than one line, specify the number of lines: 


delete 6 


Or, if you want to delete all the lines from the current line to the end 
of the file, use an asterisk (*): 


delete * 


If you want to delete an undetermined number of lines, up to a 
particular character string, you can use the DSTRING subcommand: 


dstring /weather/ 
When this subcommand is entered, all the lines from and including the 
current line down to and including the line ‘just above the line 


containing the character string "WEATHER" are deleted. The current line 
pointer is positioned at the line that has "WEATHER" on it. 


If you want to replace a line with another line, you can’ use the 
REPLACE subcommand: 
replace Me ok oe a ok 
The current line is deleted and the line "*******" 35 inserted in its 
place. The current line pointer is not moved. 
To replace an existing line with many new lines, you can issue the 
REPLACE subcommand with no new data line: 
replace 


The editor deletes the current line and enters input mode. 


Inserting Lines 


You can insert a single line of data between existing lines using the 
INPUT subcommand followed by the line of data you want inserted. For 
example: 

input * this subroutine is for testing only 


inserts a single line following the current line. If you want to insert 
many lines, you can issue the INPUT subcommand to enter input mode. 
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You can also add new lines to a file by using the GETFILE subcommand. 
This allows you to copy lines from other files to include in the file 
you are editing or creating. For example: 


getfile single items c 


inserts all the lines in the file SINGLE ITEMS C immediately following 
the current line pointer. The line pointer is positioned at’ the last 
line that was read in. 


You could also specify: 
getfile double items c 10 25 


to copy 25 lines, beginning with the tenth line, from the file DOUBLE 
ITEMS C. 


The $MOVE and $DUP EDIT macros provide two additional ways of adding 
lines into a file in a particular fosition. The $MOVE macro moves lines 
from one place ina file to another, and deletes them from their former 
position. For example, if you want to move 10 lines, beginning with the 
current line, to follow a line 9 lines above the current line, you can 
enter: 


$move 10 up 8 
The $DUP macro duplicates the current line a specified number of 
times, and inserts the new lines immediately following the current line. 
For example: 


$dup 3 


creates 3 copies of the current line, and leaves the current line 
pointer positioned at the last copy. 


Describing Data File Characteristics 


When you issue the EDIT command to create a new file, the editor checks 
the filetype. If it is one of the reserved filetypes, the editor may 
assign particular attributes to it, which can simplify the editing 
process for you. The default attributes assigned to most filetypes are 
as follows: 


e Fixed-length, 80-character records 


e All alphabetic characters are translated to uppercase, regardless of 
how they are entered 


e Input lines are truncated in column 80 


e Tab settings are in columns 1, 6, 11, 16, 21, .~.-. 51, 61, and So on, 
and the tab characters are expanded to blanks 


e Records are not serialized 
The filetypes for some CMS commands and for the language processors 
deviate from these default values. Some of the attributes assigned to 


files and how you can adjust them to suit your needs are discussed 
below. 
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RECORD LENGTH 
You can specify the logical record length of a file you are creating on 
the EDIT command line: 

edit new file (lrecl 130 


If you do not specify a record length, the editor assuges' the 
following defaults: 


e For editing old files, the existing record length is used. 
e For creating new files, the following default values are in effect: 


Filetype Record Length Format 
EXEC 80 characters Variable 
FREEFORT 81 characters Variable 
LISTING 121 characters Variable 
SCRIPT 132 characters Variable 
VSBDATA 132 characters Variable 
All others 80 Fixed 


If you edit a variable-length file and the existing record length is 
less than the default for the filetype, the record length is taken fron 
the default value. | 


When you use the LRECL option of the EDIT command you can override 
these default record lengths; you can also change the record lengths of 
existing files to make them larger, but not smaller. 


If you try to override the record length of an existing file and make 
it smaller, the editor displays an error message, and you must issue the 
EDIT command again with a larger record length. For example, suppose 
you have on your B-disk a file named MYFILE FREEFORT, which was created 
with the default record length of 81. If you try to edit that file by 
issuing: 

edit myfile freefort b (lrecl 72 
the editor displays the message: 

GIVE A LARGER RECORD LENGTH. 
You must then issue the EDIT command again and either specify a length 
of 81 or more, or allow it to default to the current record length of 
the file. 

You can use the COPYFILE command to increase or decrease the record 
length of a file before you edit it. For example, if you have 
fixed-length, 132-character records ina file, and you want to truncate 
all the records at column 80 and create a file with 80-character 
records, you could issue the command: 


copyfile extra funds a (lrecl 80 
Long Records 


The largest record you can edit with the editor is 160 characters. A 
file with record length up to 160 bytes (for example, a listing file 
created by a DOS program) can be displayed and edited. 


The largest record you can create with the CMS editor, however, is 
130 characters using a 3270 display terminal and 134 characters using a 
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typewriter terminal such as a 2741 or 1050. If you enter more than 130 
characters on a 3270, the record is truncated to 130 characters when you 
press the Enter key. Note that as the line is truncated to _ 130 
characters, the CMS editor will not know the actual line length entered, 
and will not issue the "TRUNCATED" message. If you type more than 134 
characters ona line using a typewriter terminal, CP generates an 
attention interruption to your virtual machine and the input line is 
lost when you press the Return Key. 


For most purposes, you will not need to create records longer than 
130 characters. If it is necessary, you can expand a record that you 
have entered. You do this by issuing the CHANGE subcommand with 
operands, to add more characters to the record (for example, by changing 
a 1-character string to a 31-character string). However, if a record is 
longer than 130 characters, the CHANGE subcommand without operands will 
cause truncation to 130 characters. 


You cannot create a record that is longer than the record length of 
the file. For example, if the file you are editing has a default record 
length of 80, or if you specified LRECL 80 when you created the file, 
the editor truncates all records to 80 characters. 


Record Length and File Size 


There is a relationship between the record length of a file and the 
Maximum number of records it can contain. Figure 6 shows’ the 
approximate number of records, rounded to the nearest hundred, that the 
CMS Editor can handle in a virtual machine with different amounts of 
virtual storage. 


| Virtual Machine Size 


| Record Scien cu ncaa 
| Length | 320K | 512K | 768K |1024K | 
80 Characters } 1700 | 3800 | 6800 {| 9800 
, 120 Characters { 1100 | 2600 | 4700 | 6800 
132 Characters | 1100 | 2400 | 4300 | 6200 
160 Characters {| 900 | 2000 4 3600 | 5100 


ee ce a ee a ee 
Figure 7. Number of Records Handled by the CMS Editor 


RECORD FORMAT 


With the CMS Editor, you can create either fixed- or variable-length 
files. Except for the filetypes EXEC, LISTING, FREEFORT, SCRIPT, and 
VSBDATA, all the files you create have fixed-length records, by default. 
You can change the format of a file at any time during an editing 
session by using the RECFM subcommand: 


recfm v 
This changes the record format to variable-length. This does not change 
the record length; in order to add new records with a greater length, 


you must write the file onto disk and then reissue the EDIT command 
using the LRECL option. 
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The COPYFILE command also has an RECFM option, so that you can change 
the record format of a file without editing it. The command: 


copyfile * requests a1 (recfm v trunc 


changes the record formats of all the files with a filetype of REQUESTS 
on your A-disk to variable-length. The TRUNC option specifies that you 
want trailing blanks removed from each of the records. When you are 
editing a file with variable-length records, trailing blanks are 
truncated when you write the file onto disk with the FILE or SAVE 
subcommand. (In VSBDATA files, however, blanks are not truncated.) 


USING SPECIAL CHARACTERS 


The IMAGE and CASE subcommands control how data, once entered on an 
input line, is going to be represented in a file. The specific 
characters affected, and the subcommands that control their 
representation, are: 


e Alphabetic characters: CASE subcommand 


e Tab characters (X'05'): IMAGE subcommand (ON and OFF operands) 
e Backspaces (X'16"): IMAGE subcommand (CANON operand) 


Alphabetic Characters 


If you are using a terminal that has only uppercase characters, you do 
not need to use the CASE subcommand; all of the alphabetic characters 
you enter are uppercase. On terminals equipped with both uppercase and 
lowercase letters, all lowercase alphabetic characters are converted to 
uppercase in your file, regardless of how you enter them. If you are 
creating a file and you want it to contain both uppercase and lowercase 
letters you can use the subcommand: 


case 2D 


The "M" stands for "mixed." This attribute is not stored with the file 
on disk. If you create a new file, and you issue the CASE M subcomnand, 
all the lowercase characters you enter remain in lowercase. If you 
subsequently file the file and later edit it again, you must issue the 
CASE M subcommand again tec locate or enter lowercase data. 


There are two reserved filetypes for which uppercase and lowercase is 
the default. These are SCRIPT and MEMO, both of which are text or 
document-oriented filetypes. For most programming applications, you do 
not need to use lowercase letters. 


Tab Characters 


Logical tab settings indicate the column positions where fields within a 
record begin. These logical tab settings do not necessarily correspond 
to the physical tab settings on a typewriter terminal. What happens 
when you press the Tab key on a typewriter terminal depends on whether 
the image setting is on or off. The default for all filetypes except 
SCRIPT is IMAGE ON. You can change the default by issuing the 
subcommand: 


image off 
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If the image setting is on, when you press the Tab key the editor 
replaces the tab characters with blanks, starting at the column where 
you pressed the Tab key, and ending at the last column before the next 
logical tab setting. The next character entered after the tab becomes 
the first character of the next field. For example, if you enter: 


tabset 1 15 


and then enter a line that begins with a tab character, the first data 
character following the tab is written into the file in column 15, 
regardless of the tab stop on your terminal. 


If the image setting is off, the tab character, X'05", is inserted in 
the record, just as any other data character is inserted. No blanks are 
inserted. 


If you want to insert a tab character (X'05"') into a record and the 
image setting is on, you can do one of the following: 


1. Set IMAGE OFF before you enter or edit the record, and then use the 
Tab key as a character key. 


2. Enter some other character at the appropriate place in the record, 
and use the ALTER subcommand to alter that character toa X'05'°. 


SETTING TABS: When you create a file, there are logical tab settings in 
effect, so that you do not need to set them. The default values for the 
language processors correspond to the columns used by those processors. 
If you want to change them, or if you are creating a file with a 
nonreserved filetype, you may want to set them yourself. Use the TABSET 
subcommand, for example: 


tabset 1 12 20 28 72 
Then, regardless of what physical tab stops are in effect for your 


terminal, when you press the Tab key with image setting ON, the data you 
enter is spaced to the appropriate columns. 


See Figure 8 for the default tab settings used by the CMS Editor. 


Se ae ne Ep Eee Ng va Pho eT Cee ee ey ae ee eS 
| Filetype | Default Tab Settings [ 


J] ee 
| ASSEMBLE, MACRO, COPY, UPDATE, | 1, 10, 16, 30, 35, 40, 45, 50, 55, 60, 65, 70 { 
| UPDT, ASM3705, MACLIB, XEDIT | | 


a a a i ee 

|AMSERV, ESERV | 2, 5, 10, 15, 20, 25, 30, 35, 40, 45, 50, 55, 60 | 

| FORTRAN | 1, 7, 10, 15, 20, 25, 30, 80 | 

—-+4 

| FREEPORT { 9, 15, 18, 23, 33, 38, 81 | 

——-44 

{DIRECT, JOB | 1, 5, 10, 15, 20, 25, 30, 35, 40, 45, 50, 55, 60, 65, {| 

| | 70, 75 | 

Ht 

[ EXEC, CNTRL | 1, 5, 8, 17, 27, 31 | 

—-—-—___-________———_- CO OOOO! OL. sd 

| COBOL 1 1, 8, 12, 20, 28, 36, 44, 68, 72, 80 { 
}—-—__—______————— xX 

|BASIC, BASDATA, VSBASIC | 7, 10, 15, 20, 25, 30, 80 | 

4 

|VSBDATA, SCRIPT, MEMO, 1 1, 5, 10, 15, 20, 25, 30, 35, 40, 45, 50, 55, 60, 65, | 

| LISTING, ******* | 70, 75, 80, 85, 90, 95, 100, 105, 110, 115, 120 | 

~ 4 

{PLI, PLIOPT | o: 4, 7, 10, 13, 16, 19, 22, 25, 31, 37, 43, 49, 55, | 


ne ee 


Figure 8. Default Tab Settings 
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When you are specifying tab settings for files, the first tab setting 
you specify should be the column in which you want your data to begin. 
The editor will not allow you to place data in a column preceding this 
one. For example, if you issue: 


tabset 5 10 15 20 
and enter an input line: 
input This is a line 


Columns 1, 2, 3, and 4 contain blanks; text begins in column 5. 


Backspaces 


For most of your applications, you do not need to underscore or 
overstrike characters or character strings. If you are using a 
typewriter terminal and are typing files that use backspaces and 
underscores, you should use either the IMAGE OFF or IMAGE CANON 
subcommands so that the editor handles the backspaces properly. IMAGE 
CANON is the default value for SCRIPT files. 


CANON means that regardless of how the characters are keyed in 
(characters, backspaces, underscores), the editor orders, or canonizes, 
the characters in the file as: Character-backspace-underscore, 
character-backspace-underscore, and so on. If, for example, you want an 
input line to look like: 


ABC 
You could enter it as: 
ABC, 3 backspaces, 3 underscores 
ae ae 
3 underscores, 3 backspaces, ABC 
A typewriter types out the line in the following order: 


A backspace, underscore 

B backspace, underscore 

C backspace, underscore, which results in: 
ABC 


If you need to modify a line that has backspaces, and you do not want 
to rekey all of the characters, hacksraces, and overstrike characters in 
a CHANGE or REPLACE subcommand, you can use the ALTER subcommand to 
alter all of the backspaces to some other character and use a global 
CHANGE command. For example, the following sequences’ shows how to 
delete all of the backspace characters on a line: 


AAAAA 

alter 16 + 1 * 
_tA_+A_+A_+A_+A 
change /_+// 1 * 
AAAAA 


This technique may also be useful on a display terminal. 
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SETTING TRUNCATION LIMITS 


Every CMS file that you edit has a truncation column setting: this 
column represents the last character position in a record into which you 
can enter data. When you try to input a record that is longer than the 
truncation column, the record is truncated, and the editor sends you a 
message telling you that it has been truncated. 


You can change the truncation column setting with the TRUNC 
subcommand. For example, if you are creating a file with a record length 
of 80 and wish to insert some records that do not extend beyond column 
20, you could issue the subcommand: 


trunc 20 


Then, when you enter data lines, any line that is longer than 20 
characters is truncated and the editor sends you a message. If you are 
entering data in input mode, your virtual machine remains in input mode. 


When you use the CHANGE subcommand to modify records, the column at 
which truncation occurs is determined by the current zone setting. If 
you change a character string in a line to a longer string, and the 
resultant line extends beyond the current end zone, you receive’ the 
message: 


TRUNCATED. 


If you need to create a line longer than the current end zone setting, 
use the ZONE subcommand to increase the setting. The subcommand: 


zone 1 * 


extends the zone to the record length of the file. If the end zone 
already equals the record length, you have to write the file onto disk 
and reissue the EDIT subcommand specifying a longer record length. 


For most filetypes, the truncation and end zone columns are the sane 
as the record length. For some filetypes, however, data is truncated 
short of the record length. The default truncation and end zone colugns 
are: 


Filetype Column 
ASSEMBLE, MACRO 71. 
UPDATE, 
UPDT xxxx 
AMSERV, COBOL, 72 


DIRECT, FORTRAN 
PLI, PLIOPT 


All other filetypes are truncated at their record length. 


You can, when creating files for your own uses, set truncation 
columns so that data does not extend beyond particular columns. 


ENTERING A CONTINUATION CHARACTER IN COLUMN 72 


When you are using the editor to enter source records for an assembler 
language progran and you need to enter a continuation character in 
column 72, or whenever you want to enter data outside a particular 
truncation setting, you can use the following technique. Note that this 
technique will not work if CANON is specified on the IMAGE subcommand. 
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1. Change the truncation setting to 72, so that the editor does not 
truncate the continuation character: 


trunc 72 

2. Use the TABSET subcommand to set the left margin at column 72: 
tabset 72 

3. Use the OVERLAY subcommand to overlay an asterisk in column 72: 
overlay * 


Since the left margin is set at 72, the OVERLAY subcommand line 
results in the character * being placed in column 72. 


4. Restore the editor truncation and tab settings: 


trunc 71 
tabset 1 10 16 31 36 41 51 6171 81 


Note: If you issue the PRESERVE subcommand before you change the 
truncation and tab settings, then after you enter the OVERLAY 
subcommand, you can restore them with the RESTORE subcommand. See 
"Preserving and Restoring CMS Editor Settings." 


Use the $MARK Edit Macro: Another way to insert a continuation character 
is to use the $MARK edit macro. You can find out if the $MARK edit macro 
is available on your system by entering, in the CMS or CMS’- subset 


environment: 
listfile $mark exec * 

If it is not available on your system, you can create the $MARK edit 
macro for your own use. See "Section 17. Writing Edit Macros" in "Part 
3. Learning to Use EXEC." 

If you have the $MARK macro, then when you need to enter a 
continuation character, you can enter a null line to get into edit node, 
issue the command: 


$mark 


and then return to input mode to continue entering text. 


SERIALIZING RECORDS 


Some CMS files that you create are automatically serialized for you. 
This means that columns 73 to 80 of each record contain an identifier in 
the form: 


CCCXXxxx 
where ccc are the first three characters of the filename and xxxxx iS a 


sequence number. Sequence numbers begin at 00010 and are incremented by 
10. 


The filetypes that are automatically serialized in columns 73 to 80 
are: 
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ASSEMBLE FORTRAN PLIOPT 
DIRECT COBOL UPDATE 
MACRO PLI UPDTxxxx 


You can serialize any file that has fixed-length, 80-character 
records by using the SERIAL subcommand: 


serial on 
The SERIAL subcommand can also be used to: 
e Assign a particular three-character identifier: 
serial abc 
e Specify that all eight bytes of the sequence field be used to contain 
humbers: 
serial all 
°e Specify a sequence increment other than 10: 
serial on 100 
ste eet Se 
serial ccc 100 


e Indicate that no sequence numbers are to be assigned to new records 
being inserted: 


serial off 


When you create a file or edit a file with sequence numbers, the 
sequence numbers are not written or updated until you issue a FILE or 
SAVE subcommand. Because the end verification columns for the filetypes 
that are automatically serialized are the same as their truncation 
columns, you do not see the serial numbers unless you specify: 


verify * 
verify 80 


Although the serial numbers are not displayed while you edit the file, 
they do appear on your output listings or printer files. 


If you are editing files with the following filetypes: 


BASIC 
VSBASIC 
FREEFORT 


the sequence numbers are onthe left. For BASIC and VSBASIC files, 
columns 1-5 are used; numbers are blank-padded to the left. For 
FREEFORT files, the sequence numbers use columns 1-8, and are 
zero-padded to the left. To edit these files, you should use line-nunmber 
editing, which is discussed next. 
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LINE-NUMBER EDITING 


To edit a file by line numbers means that when you are adding new lines 
to a file or referencing lines that you wish to change, you’ refer to 
them by their line, or sequence numbers, rather than by character 
strings. You can use right line-number editing only on files with 
fixed-length, 80-character records. 


If you want to edit by line numbers, issue the subcomnand: 
linemode right 
linemode left 
where "right" indicates that the sequence numbers are on the right, in 
columns 76-80, and "left" indicates you want sequence numbers on the 
left in columns 1-5. LINEMODE LEFT is the default for BASIC, VSBASIC, 


and FREEFORT files. You do not have to specify it. You must specify 
LINEMODE for files with other filetypes. 


If you specify LINEMODE RIGHT to use line-number editing on a 
typewriter terminal, the line numbers are displayed on the left, asa 
convenience, while you edit the file. 


When you are using line-number editing in input mode, you are 
prompted to enter lines; the line numbers are in increments of 10. For 
example, when you are creating a new file, you are prompted for the 
first line number as follows: 


10 


On a typewriter terminal, you enter your input line following the 10. 
When you press the carriage return, you are prompted again: 


20 


and you continue entering lines in this manner until you enter a null 
line. 


You can change the prompting increment to a larger or smaller number 
with the PROMPT subcommand: 


prompt 100 


When you are in edit mode you can locate a line by giving its line 
number: 


700 


This is the nnnnn subcommand. In line-number editing, you use it instead 
of the INPUT subcommand to insert a single line of text. For example: 


905 x =a ¥*b 


inserts the text line "X = A * B" in the proper sequence in the file. 
If you use "nnnnn text" specifying the number of a line that already 
exists, that line is replaced; the current line pointer is moved to 
point to it. 


The EDIT subcommands that you normally use for context editing, such 


as CHANGE, ALTER, LOCATE, UP, DOWN, and so forth, can also be used when 
you are line-number editing; their operation does not change. 
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RENUMBERING LINES 


When you are using line-number editing, the editor uses’ the prompting 
increment set by the PROMPT subcommand. However, when you begin adding 
lines of data between existing lines, the editor uses an algorithm to 
select a line number between the current line number and the next line 
number. If a prompting number cannot be generated because the current 
line number andthe next line number differ only by one, the editor 
displays the message: 
RENUMBER LINES 


and you must reseguence the line numbers in the file before you can 
continue line-number editing. 


You can resequence the line numbers in one of three ways: 
1. If you are a VSBASIC or FREEFORT user, you may use the RENUM 
subcommand: 
renum 
This subcommand resolves all references to lines that are 
renumbered. 
2. If you are using right-handed line-number editing, you must: 
a. Turn off line-number editing: 
linemode off 
b. If you want to change the three-character identifier or specify 
eight-character sequence numbers, issue the SERIAL subconmnand, 
for example: 
serial all 
If you want to use the default serialization setting, you do not 
need to issue the SERIAL sukcommand. 
c. Issue the SAVE subconmmand: 


save 


d. Reissue the LINEMODE subcommand and continue line-number 
editing: 


linemode right 
3. If you are using left-handed line-number editing for a filetype 
other than VSBASIC or FREEFORT, you must manually change individual 
line numbers using EDIT subcommands. In order to modify the line 


humbers, you must change the zone setting and the tab setting: 


zone 1 * 
tabset 1 6 


so that you can place data in columns 1 through 6. 
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When you are using right-handed line-number editing, anda FILE, 
SAVE, or automatic save request is issued, the editor does not 
resequence the serial numbers, but displays the message: 


RESERIALIZATION SUPPRESSED 


so that the lines numbers that are currently saved on disk match the 
line numbers in the file. You must cancel line-number editing (using the 
LINEMODE OFF subcommand) before you can issue a FILE or SAVE subcommand 
if you want to update the sequence numbers. 


Controlling the CMS Editor 


There are a number of EDIT subcommands that you can use to maximize the 
use of the editor in CMS. A few techniques are suggested here; as you 
become more familiar with VM/SP and CMS you will develop additional 
techniques for your own applications. 


COMMUNICATING WITH CMS AND CP 


Often during a terminal session, you may need to issue a CMS command or 
a CP command. You can issue certain CMS commands and most CP commands 
without terminating the edit session. The EDIT subcommand CMS places 
your virtual machine in the CMS subset mode of the editor, where you can 
issue CMS commands that do not modify your virtual storage. Remember 
that the editor is uSing your virtual storage; if you overlay it with 
any other command or program, you will not be able to finish your 
editing. 


One occasion when you may want to enter CMS subset is when you want 
to issue a GETFILE subcommand for a file on one of your virtual disks 
and you have not accessed the disk. You can enter: 

cns 
The editor responds: 
CMS SUBSET 
Then you can enter: 
access 193 b/fa 
return 


get setup script b 


The special CMS SUBSET command RETURN returns your virtual machine to 
edit mode. 


You can enter CP commands from CMS subset, or you can issue then 
directly from edit mode or input mode with the #CP function. fFor 
example, if you are inputting lines into a file and another user sends 
you a message, you can reply without leaving input mode: 

#cp m oph i will call you later 


If you enter #CP without specifying a command line, you receive the 
message: 


CP 
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which indicates that your virtual machine is in the CP command 
environment, and you can issue CP commands. You would not, however, 
want to issue any CP command that would modify your virtual storage or 
alter the status of the disk on which you want to write the file. 


To return to edit or input mode from CP, use the CP command, BEGIN. 
If you are working at a display terminal and the screen image does not 


reappear, enter the TYPE command to cause the editor to redisplay the 
screen. 


CHANGING FILE IDENTIFIERS 


There are several methods you can use to change a file identifier before 
writing the file onto disk. You can use the FNAME and FMODE subcommands 
to change the filename or filemode, or you can issue a FILE or SAVE 
subcommand specifying a new file identifier. 


For example, if you want to create several copies of a file while you 
are using the editor, you can issue a series of FNAME subcommands, 
followed by SAVE subcommands, as follows: 


edit test file 
EDIT: 


fn testi#save 


fn test2#save 


fn test3#file 


Or, you could issue the SAVE and FILE subcommands as follows: 


edit test file 


save test! 


save test2 


file test3 


In both of the preceding examples, when the FILE subcommand is executed, 
there are files named TEST FILE, TEST1 FILE, TEST2 FILE, and TEST3 FILE. 
The original TEST FILE is unchanged. 


To change the filemode letter of a disk, use the FMODE subcommand. 
You can do this in cases where you have begun editing a file that is on 
a read-only disk, and want to write it. Since you cannot write a file 
onto a read-only disk, you can issue the FMODE subcommand to change the 
mode before filing it: 
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fmode a 
file 


Or, you can use the FILE (or SAVE) subcommand specifying a complete file J 
identifier: 


file test file a 


You should remember, however, that when you write a file onto disk, 
it replaces any existing file that has the same identifier. The editor 
does not issue any warning or informational messages. If you are 
changing a file identifier while you are editing the file, you must be 
careful that you do not unintentionally overlay existing files. To 
verify the existence of a file, you can enter CMS subset and issue the 
STATE or LISTFILE commands. 


CONTROLLING THE CMS EDITOR'S DISPLAYS 


When you are uSing a typewriter terminal, you may not always want to see 
the editor verify the results of each of your subcommands. Particularly 
when you are making global changes, you may not want to see each line 
displayed as it is changed. You can issue the VERIFY subcommand with 
the OFF operand to instruct the editor not to display anything unless 
specifically requested. After you issue; 


verify off 


lines that are normally displayed as a result of a subcommand that moves 

the current line pointer (UP, DOWN, TOP, BOTTOM, and so forth), or that 

changes a line (CHANGE, ALTER, and so forth), are not displayed. If the 

current line pointer moves to the end of the file, however, the editor } 
always displays the EOF: message. 


If you are editing with verification off, then you’ nmust be 
particularly careful to stay aware of the position of your current line 
pointer. You can display the current line at any time using the TYPE 
subcommand: 


type 
Long and Short Error Messages: When you enter an invalid subconmmand 


while you are using the editor, the editor normally responds with the 
error message: 


?EDIT: line... 
displaying the line that it did not recognize. If you prefer, you can 
issue the SHORT subcommand so that instead of receiving the long form of 
the error, you receive the short form, which is: 


= 


When you issue an invalid edit macro request (any line that begins with 
a $), you receive the message: 


a$ 


To resume receiving the long form of the error message, use the LONG 
-Subcommand: 


long 


LONG and SHORT control the display of the error message regardless of 
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whether you are editing with verification on or off. 


On a display terminal, all EDIT messages that are displayed at the 
top of the screen, including error messages and ‘?EDIT:' messages, are 
highlighted. 


PRESERVING AND RESTORING CMS EDITOR SETTINGS 


The PRESERVE and RESTORE subcommands are used together; the PRESERVE 
subcommand saves the settings of the EDIT subcommands' that control the 
file format, message and verification display, and file identifier. If 
you are editing a file and you want to temporarily change some of these 
settings, issue the PRESERVE subcommand to save their current status. 
When you have finished your temporary edit project, issue the RESTORE 
subcommand to restore the settings. 


For example, if you are editing a SCRIPT file and want to change the 
image setting to create a particular format, you can enter: 


preserve 

image on 

tabset 1 15 40 60 72 
zone 1 72 

trunc 72 


When you have finished entering data using these settings, you can issue 
the subcommand: 


restore 


to restore the default settings for SCRIPT filetypes. 


X, Y, =, ? SUBCOMMANDS 


The X, Y, =, and ? subcommands all perform very simple functions that 
can help you to extend the language of the CMS editor. They allow you 
to manipulate, reuse, or interrogate EDIT subcommands. 


If you have an editing project in which you have to execute the same 


subcommand a number of times, you can assign it to the X or Y 
subcommands, as follows: 


x locate /insert here/ 
y getfile insert file c 


Each time that you enter the X subcommand: 
X 


the command line LOCATE /INSERT HERE/ is executed, and every time you 
enter the Y subcommand: 


Y 


the GETFILE subcommand is executed. 


When you specify a number following an X or Y subcommand, the 
subcommand assigned to X or ¥ is executed the specified number of times; 
for example: 

x locate /aa/ 
x 10 
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the LOCATE subcommand line is executed 10 times before you can enter 
another EDIT subcommand. 


Another method of re-executing a particular subcommand is to use the 
= (REUSE) subcommand. For example, if you enter: 


locate /ard/ 
AARDVARK 


the LOCATE subcommand is re-executed seven times. 


What the = (REUSE) subcommand actually does is to _ stack the 
Ssubcommand in the console stack. Since CMS, and the editor, read fron 
the console stack before reading from the terminal, the lines in the 
stack execute before a read request is presented to the terminal. When 
you enter multiple equal signs, the subcommand is stacked once for each 
equal sign you enter. 


You can also stack an additional EDIT subcommand following an equal 


Sign. The subcommand line is also stacked, but it is stacked LIFO 
(last-in, first-out) so that it executes before the stacked subcommand. 
For example, if you enter: 


delete 
= next 


a DELETE subcommand is executed, then a DELETE subcommand is stacked, 
and a NEXT subcommand is stacked in front of it. Then the stacked lines 
are read in and executed. The above sequence has the same effect as if 
you enter: 


delete 
next 
delete 
In addition to stacking the last subcommand executed, you can also 
find out what it was, using the ? subcommand. For example, if you 
enter: 


next 10 
? 


the editor displays: 


NEXT 10 
Since the subcommand line NEXT 10 was the last subcommand entered, if 
you enter an = subcommand, it is executed again. You cannot stack a ? 
subcommand. 


Note: The ? subcommand, ona display terminal, copies the last EDIT 
subcommand into the user input area, where you may modify it before 
re-entering it. 


WHAT TO DO WHEN YOU RUN OUT OF SPACE 


There are two situations that may prevent you from continuing an edit 
session or from writing a file onto disk. You should be aware of these 
situations, know how to avoid them, and how to recover from then, should 
they occur. 
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When you issue the EDIT command to edit a file, the editor copies the 
file into virtual storage. If it is a large file, or you have made many 
additions to it, the editor may run out of storage space. If it does, it 
issues the message: 


AVAILABLE STORAGE IS NOW FULL 
When this happens, you cannot make any changes or additions to the file 
unless you first delete some lines. If you attempt to add a line, the 
editor issues the message: 


NO ROO’ 


If you were entering data in input mode, your virtual machine is 
returned to edit mode, and you may receive the message: 


STACKED LINES CLEARED 


which indicates that any additional lines you entered are cleared and 
will not be processed. 


You should use the FILE subcommand to write the file onto disk. If 
you want to continue editing, you should see that the editor has more 
storage space to work with. To do this, you can find out how large your 
virtual machine is and then increase its size. To find out’ the size, 
issue the CP QUERY command: 


cp query virtual storage 
If the response is: 
STORAGE = 256K 


You might want to redefine your storage to 512K. Use the CP command 
DEFINE, as follows: 


cp define storage 512k 


This command resets your virtual machine, and you must issue the CP IPL 
command to reload the CMS system before you can continue editing. 


If a file is very large, the editor may not have enough space to 
allow you to edit it using the EDIT command. The message: 


DMSEDI132S FILE ‘fn ft fm’ TOO LARGE 


indicates that you must obtain more storage space before you can edit 
the file. If this is the case, or if you are editing large files, you 
should redefine your storage before beginning the terminal session. If 
this happens consistently, you should see your installation support 
personnel about having the directory entry for your userid updated so 
that you have a large storage size to begin with. 


splitting CMS Files Into Smaller Files 


If the file you are editing is too large, and the data it contains does 
not have to be in one file, you can split the file into smaller files, 
so that it is easier to work with. Two of the methods you can use to do 
this are described below. 


Use the COPYFILE Command: You can use the COPYFILE command to copy 
portions of a file into separate files, and then delete the copied lines 
from the original file. For example, if you have a file named TEST FILE 
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that has 1000 records, and you want to split it into four files, you 
could enter: 


copyfile test file a test1 file a (from 1 for 250 

copyfile test file a test2 file a (from 251 for 250 
copyfile test file a test3 file a (from 501 for 250 
copyfile test file a test4 file a (from 751 for 250 


When these COPYFILE commands are complete, you have four files 
containing the information from the original TEST FILE, which you can 
erase: 


erase test file 


Use the Editor: If you use the editor to create smaller files, you can 
edit them as you copy then, that is, if you have other changes that you 
want to make to the data. To copy files with the editor, you use the 
GETFILE subcommand. Using the file TEST FILE as an example, you might 
enter: 


edit test1 file 
getfile test file a 1 250 


file 
edit test2 file 
getfile test file a 251 250 


Again, you could erase the original TEST FILE when you are through with 
your edit session. 


When you enter a FILE or SAVE subcommand or when an automatic save 
request is issued, the editor writes a copy of the file you are editing 
onto disk, and names it EDIT CMSDT1. If this causes the disk to become 
full, you receive the message: 


DMSBWR170S DISK 'tmode(cuu)* IS FULL 
The editor erases the workfile, and issues the message: 
SET NEW FILEMODE, OR ENTER CMS SUBSET AND CLEAR SOME SPACE 


The original file (as last written onto disk) remains unchanged. You 
can use the CMS subcommand to enter CMS subset, and erase any files that 
you do not need. You can use the LISIFILE command to list the files on 
the disk, then the ERASE command to erase the unwanted files. 


If you cannot erase any of the files on the disk, there are several 
alternate recovery paths you can take: 


1. If you have another read/write disk accessed, you can use the FMODE 
Subcommand to change the filemode of the file, so that when you 
file it, it is written to the other disk. If you have a read/write 
disk that is not accessed, you can access it in CMS subset. After 
filing the file on the second disk, erase the original copy, and 
then use the COPYFILE command to transfer the file back to its 
original disk. 
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2. If you do not have any other read/write disk in your virtual 
machine, you may be able to transfer some of your files to another 
user, uSing either the SENDFILE, PUNCH or DISK command in CMS 
subset. When the files have been read onto the other user's disk, 
you can erase them from your disk. Then, return to edit mode and 
issue the FILE subcomnmand. 


3. In CMS subset, erase the original disk file (if it existed), then 
return to edit mode and file the copy that you are editing. You 
should not use this method unless absolutely necessary, since any 
unexpected problems may result in the loss of both the disk file 
and the Copy. 


After you use the FILE subcommand to write the file onto disk, you 
should continue erasing any files you no longer need. 


The System Product Editor 


The System Product Editor provides full screen and file manipulation 
capabilities not offered by the CMS Editor. 


This editor has the following advantages: 


e Full screen support for IBM 3270 Display Terminals is available 
including: 


- the ability to display multiple views of the same file or of 
different files 


- automatic "wrapping" of lines that are wider than a screen line 


- the ability to enter selected subcommands directly on the displayed 
lines 


- the ability to define the screen format according to individual 
preferences 


e Extended string search facilities are provided for improved text 
processing. 


e A variety of macros, that use the EXEC 2 interpreter are offered. 


e An enhanced set of functions to handle program development is 
available, including automatic update generation. 


e The ability to import and export data between files is provided. 
For complete information about the System Product Editor, see the 


VWM/SP System Product Editor User's Guide and the VM/SP System Product 
Editor Command and Macro Reference. 
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Summary of CMS EDIT Subcommands 


The EDIT subcommands, and their formats, are shown in Figure 9. Refer to 
the VM/SP CMS Command and Macro Reference for complete details. 


Subcommand Format | Function | 

{ 
|Scans the next n records of | 
[the file, altering the speci-— | 
{fied character, either once in| 
jeach line or for all occur— 
jrences in the line. 


7 
ALter char1 char2 | 
l 
| 


I s#* 
rc———» 
% GQ) 
Le eee 
a | 


1 {Automatically saves the file 
| jon disk after the indicated 
[ [number of lines have been 

t 4 | processed. 


AUTOsave 


1 | Points the current line 
BAckward | [pointer to a line above the 
| {line currently pointed to. 

J 


Botton | Makes the last line of the 
[file the current line. 


eeE 
Im 5 


{Indicates whether translation | 
[to uppercase is to be done, or| 
[displays the current status. 
( 


a 
be oe — 


ro4 {Changes string1 to string2 for 
CHange [/string1[ /string2[/ In Itt jjjia records or to EOF, either 
i* |*] | {for the first occurrence in 


| 1 4 | {each line or for all 
L 4 {| occurrences. 
CMS [Enters CMS subset command 
| mode. 


|Deletes n lines or to the end 


T | 
DELete | n | [of the file (*). 
| * | i 
lil { 
Ll a | ] 
ro64 | Points to the nth line fron 
DOwn [ n | {the current line. 
141 | 
L A | | 
DString /[string [/]] | Deletes all lines from the 
[current line down to the line 
{containing the indicated 
| string. 
FILE {fn [ft [fn]]] |Saves the file being edited on 


|disk or changes its identi- 
| fiers. Returns to CMS. 


—_—_ eS ae ae ee ee eee eee ee eee eee eee eee ee Cee ee eee ee eo eee ieee ieee ee ae ee ee oe eee cee eo ee ee eee ee ee ees ae a eee ee ee 
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Subcommand Format 


Find [line] 
FMode [fn ] 
FName [fn ] 


FORMat jDISPLAY 
LINE 


“ 
FOrward | n 
| 1 
L 


ee | 


Getfile fn | 
| 
L 


Fr = | 
IMAGE |ON | 
|OFF | 
|CANON| 
L J 


Input [line } 


s 
LINEmode |LEFT 
|RIGHT 


|OFF 
L 


[ee | 


[Locate ]/[string [/]] 


LONG 


Overlay [line] 


PREserve 


| Function 


| Searches the file for the 
[given line. 


[Resets or displays the 
| filemode. 


{Resets or displays the 
| filenane. 


[Switches the 3270 terminal 
| between display mode and line 
[mode. (3270 only) 


[Points to the nth line after 
{the current line. 

[ 

[ 


j|Inserts a portion or all of 
[the specified file after the 
[current line. 


jExpands text into line images 
jor displays current settings. 


[ 

[ 

| 

{Inserts a line in the file or 
{enters input mode. 


[Sets or displays current 
[setting of line—nunmber 
[|editing. 

| 

é 


{Scans file from next line for 
[first occurrence of ‘string’. 


{Enters long error message 
| mode. 


[Points to the nth line down 
| from the current line. 


|Replaces all or part of the 
j|current line. 


| Saves current mode settings. 


{|Sets or displays line number 
J|increment. Initial setting is 
(10. 


Figure 9. Summary of CMS EDIT Sukcommands and Macros (Part 2 of 4) 
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Subcommand Format | Function 


© 
fos 
H 
a 


jTerminates edit session with 
[no updates incorporated since 
j|last save request. 


[Sets or displays record format 


r a | 
RECfon | F | |for subsequent files. 

iv | [ 

| i J | 

r r 11 |Recomputes line numbers for 
RENum |strtno |incrno| | | VSBASIC and FREEFORT source 

[10 Istrtno|] | | files. 

Ll L JJ | 


1 | Executes the following OVERLAY 
| |subcommand n times. 

| [ 

( i 

= | 


eS —= 
(— # 


Replace [line] | Replaces the current line or 
[deletes the current line and 
Jenters input mode. 


REStore |Restores editor settings to 
[values last preserved. 


RETURN {Returns to edit environment 
| from CMS subset. 


or [ subcommand ] | Stacks (LIFO) the last FDIT 

= \ |subcommand that does not start 
|with REUSE or the question 
{mark (?) and then executes any 
{given EDIT subcommand. 


SAVE [fn [ft [fm]]] [Saves the file on disk and 
| stays in edit environment. 


[Displays a number of screens 
Jof data above or below the 
j[current line (3270 only). 


pe \ 


Z 

[ 
S[croll]U[p]/ | 
l 
L 


I -#*# 5 
ee | 


SERial OFF - 1 
ON |incr| 


| Turns serialization on or off 
J1 

ALL | 10 | [ 
{ 


in columns 73 through 80. 
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seq L J 
SHORT j|Enters short error message 
| mode. 

cr 1 [Stacks data lines or EDIT 
STACK | n | | subcommands in the console 

| i [ {input stack. 

4 0 l l 

{subcommand | | 

L J | 


Figure 9. Summary of CMS EDIT Subcommands and Macros (Part 3 of 4) 
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Ce ee ee a eee 
Subcommand Format | Function 


TABSet n1 [n2 ... nn] {Sets logical tab stops. 


| 
oO 
a] 


{Moves the current line pointer 
Jto the nuil line at the top 
jof the file. 


1 [Sets or displays the column of 
| { truncation. An asterisk (*) 

| [indicates the logical record 

4 | length. 


1 {Displays m lines beginning 
I | Jwith the current line. Each 
i | [line may be truncated to n 
I | | characters. 

J 4d 


1 | Moves the current line pointer 

n | | toward the top of the file. 

1 | i 
J 


l 

( 

{ 

| 

i 

; 

i 

[ 

l 

l 

| 

i 

| 

{ 

l 

l 

{ 

{ 

( 

; 

[ 

[ 

| 

[ 

1 re 1 1 |Sets, displays, or resets | 
ON | | |startcol|jendcol | | verification. An asterisk (*) | 
OFFI | 1 | * | [indicates the logical record | 
4 LL Jj J. | length. | 
i 
[ 
i 
| 
[ 
| 
[ 
i 
{ 
l 
H 
| 
l 
[ 
| 
| 
l 
| 
[ 
| 
[ 
[ 
| 
[ 
[ 
[ 


r 1 | Assigns to X or Y the given 
|subconmmand| {EDIT subcommand or executes 
| n | [the previously assigned 

| 1 | | subcommand n times. 

t A | | 


11 |Sets or displays the columns 
| | | between which editing is to 
| | [take place. 
| | 
J Jd 


*\— B 


| Displays the last EDIT 
| subcommand, except = or ?. 


on) 


jeeaae \ [text ] |Locates the line specified by 
nnnnnnnn |the given line number and 
Jinserts text, if given. 


|Duplicates the current line n 
[times. $DUP is an edit macro. 
| 
| 


$MOVE n Up m [Moves up n lines or down a 


n 
1 


me 
o 
| 
tg 

e=——§ 

ee 


Down mn [lines. $MOVE is an edit macro. | 
TO label J | 
| a ee 


Figure 9. Summary of CMS EDIT Subcommands and Macros (Part 4 of 4) 
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Section 6. Introduction to the EXEC Processors 


There are two EXEC processors available: CMS EXEC and EXEC 2. The CMS 
EXEC processor handles CMS EXEC programs, while the EXEC 2 processor 
handles EXEC 2 programs. EXEC 2 programs and procesSing are similar to 
those of the CMS EXEC. 


The CMS EXEC Processor 


A CMS EXEC processor is a CMS file that contains executable statements. 
The statements may be CMS or CP commands or EXEC control statements. 
The execution can be conditionally controlled with additional EXEC 
statements, or it may contain no EXEC statements at all. In its simplest 
form, an EXEC file may contain only one record, have no variables, and 
expect no arguments to be passed to it. In its most complex forn, it can 
contain thousands of records and may resemble a program written ina 
high-level programming language. As acCMS user, you should become 
familiar with the EXEC processor and use it often to tailor CMS commands 
to your own needs, as well as to create your own commands. 


The following is an example of a’ simple EXEC procedure that might be 
named RDLINKS EXEC: 


CP LINK DEWEY 191 291 RR DEWEY 
CP LINK LIBRARY 192 292 RR DEWEY 
ACCESS 291 B/A 

ACC 292 C/A 


When you enter: 
rdlinks 
each command line contained in the file RDLINKS EXEC is executed. 

You could also create an EXEC procedure that functions like a 
cataloged procedure, and set it up to receive an argument, so that it 
executes somewhat differently each time you invoke it. For example, a 
file named ASM EXEC contains the following: 

ASSEMBLE 6&1 
PRINT &1 LISTING 


LOAD &1 
START 


If you invoke the EXEC specifying the name of an assembler language 
source file, such as: 


aSm myprog 

the procedure executes as follows; 
ASSEMBLE MYPROG 
PRINT MYPROG LISTING 


LOAD MYPROG 
START 
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The variable &1 in the EXEC file is substituted with the argument you 
enter when you execute the EXEC. AS many as 30 arguments can be passed 
to an EXEC in this manner; the variables thus set range from &1 through 
&30. 


CREATING EXEC FILES 


EXEC files can be created with the CMS editors, by punching cards, or by 
using CMS commands or programs. When you create a file with the editor, 
records are, by default, variable-length with a logical record length of 
80 characters. EXEC can process variable-length files of up to 130 
characters. To create a variable-length EXEC file larger than 80 
characters, use the LRECL option of the EDIT command: 


edit new exec a (lrecl 130 


To convert avariable-length file to a fixed-length file, you can 
edit the EXEC file and issue the subcommand: 


recfm f 
Or, you can use the COPYFILE command: 
copyfile old exec a ({recfm f 


If you use fixed-length EXEC files, you should be aware that the EXEC 
interpreter only processes the first 72 characters of each record ina 
fixed-length file, regardless of the record length. You can, however, 
enter command or data lines that are longer than than 72 characters to 
be processed by uSing the &BEGSTACK, &BEGTYPE, &BEGPUNCH, and &BEGEMSG 
control statements preceding the line(s) you want to be processed. If 
you specify S&BEGPUNCH ALL, EXEC processes lines up to 80 characters 
long; if you specify &BEGTYPE ALL, &BEGSTACK ALL, or &BEGEMSG ALL, EXEC 
processes lines up to 130 characters. 


In variable-length EXEC files, there are no such restrictions; lines 
up to 130 characters are processed in their entirety. 


Two CMS commands create EXEC files. One is LISTFILE, which can be 
invoked with the EXEC option; it creates a file named CMS EXEC. The uses 
of CMS EXEC files are discussed under the heading "CMS EXECS and How To 
Use Them." The CMS/DOS command LISTIO creates an EXEC file named 
$LISTIO EXEC, which creates records for each of the system and 
programmer logical unit assignments. The LISTIO command and the $LISTIO 
EXEC are described in “Section 9. Developing DOS Programs Under CMS." 


INVOKING EXEC FILES 


EXEC procedures are invoked when you enter the filename of the EXEC 
file. You can precede the filename on the command line with the CMS 
command, EXEC. For example: 


exec test type list 
where TEST is the filename of the EXEC file and TYPE and LIST are 


arguments (&1, &2, and so on) you are passing to the EXEC. For example, 
an EXEC named PREPEDIT would be executed when you entered either: 
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prepedit newfile replace 

a= gp. = 

exec prepedit newfile replace 
You must precede the EXEC filename with the EXEC command when: 
e You invoke an EXEC from within another EXEC. 


e You invoke an EXEC from a progran. 
e You have the implied EXEC function set off for your virtual machine. 


The implied EXEC function is controlled by the SET command. If you 
issue the command: 


set impex off 


then you must use the EXEC command to invoke an EXEC procedure. The 
default setting is ON; you almost never need to change it. 


An EXEC procedure having a synonym defined for it can be invoked by 
its synonym if the implied EXEC (IMPEX) function is on. However, within 
an EXEC procedure, only the EXEC filename can be used. A synonym is not 
recognized within an EXEC since the synonym tables are not’ searched 
during EXEC processing. 


There is one EXEC file that you never have to specifically invoke. 


This is a PROFILE EXEC, which is automatically executed after you load 
CMS, when your A-disk is accessed. PROFILE EXECS are discussed next. 


PROFILE EXECs 


A PROFILE EXEC must have a filename of PROFILE. It can contain the CP 
and CMS commands you normally issue at the start of every terninal 
session. For example: 
e Commands that describe your terminal characteristics, such as: 

CP SET LINEDIT ON 

SET BLIP * 


SET RDYMSG SMSG 
SYNONYM MYSYN 


e Commands that spool your printer and punch for particular classes or 
characteristics: 


CP SPOOL E CLASS S HOLD 


e Commands to initialize macro and text libraries that you commonly 
uses 


GLOBAL MACLIB OSMACRO CMSLIB 
GLOBAL TXTLIB PRIVLIB 


e Commands to access disks that are a permanent part of your 
configuration: 


ACCESS 196 B 


A PROFILE EXEC file that contains all of these commands’ might look 
like this: 
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SCONTROL OFF 

CP SET LINEDIT ON 

CP SPOOL E CLASS S HOLD 

SET RDYMSG SMSG 

SET BLIP * 

SYNONYM MYSYN 

GLOBAL MACLIB OSMACRO CMSLIB 
GLOBAL TXTLIB PRIVLIB 

ACCESS 196 B 


&CONTROL OFF is an EXEC control statement that specifies that the CP 
and CMS command lines are not to’ be displayed on your terminal before 
they execute. 


A PROFILE EXEC can be as simple or as complex as you require. As an 
EXEC file, it can contain any valid EXEC control statements or CMS 
commands. The only thing that makes it special is its filenane, 
PROFILE, which causes it to be executed the first time you press the 
Return key after loading CMS. 


EXECUTING YOUR PROFILE EXEC 


Usually, the first thing you do after loading CMS is to type a CMS 
command. When you press’ the Return key to enter this command or if you 
enter a null line, CMS searches your A-disk for a file with a filename 
of PROFILE and a filetype of EXEC. If such a file exists, it is 
executed before the first CMS command you enter is executed. Because 
you do not do anything special to cause your PROFILE EXEC to execute, 
you can say that it executes "automatically." 


You can prevent your PROFILE EXEC from executing automatically by 
entering: 
access (noprof) 
as the first CMS command after you IPL CMS. You can enter: 
profile 
at any time during a CMS session to execute the PROFILE EXEC, if you had 
accessed your A-disk without it, or if you had made changes’ to it and 


wanted to execute it, or if you had changed your virtual machine and 
wanted to restore itsS original characteristics. 


CMS EXECs and How To Use Them 


A file named CMS EXEC is created when you use the EXEC option of the 
LISTFILE command; for example: 


listfile pr* document a (exec 
The usual display that results from this LISTFILE command is a list of 
all the files on your A-disk with a filetype of DOCUMENT that have 
filenames beginning with the characters "PR". CMS, however, creates a 
CMS EXEC file that contains a record for each file that would be listed. 
The records are in the fornat: 


&1 &2 filename filetype filemode 
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Column 1 is blank. Now, if you have the following files on your A-disk: 


PRFILE1 DOCUMENT 
PRFILE2 DOCUMENT 
PRFILE3 DOCUMENT 
PRFILE4Y DOCUMENT 


The CMS EXEC file would contain the records: 


&€1&2 PRFILE1 DOCUMENT At 
61 &2 PRFILE2 DOCUMENT At 
61 &2 PRFILE3 DOCUMENT A1 
&1 &2 PRFILE4 DOCUMENT A1 


In the preceding lines, &1 and &2 are variables that can receive values 
from arguments you pass’ to the EXEC when you execute it. For example, 
if you execute this CMS EXEC by issuing: 


cms disk dump 


the EXEC interpreter substitutes, on each line, the variable &1 with the 
DISK and the variable &2 with DUMP and executes the commands: 


DISK DUMP PRFILE1 DOCUMENT Al 
DISK DUMP PRFILE2 DOCUMENT A1 
DISK DUMP PRFILE3 DOCUMENT At 
DISK DUMP PRFILE4 DOCUMENT Al 


You can use this technigue to transfer a number of files to another 
user. You should remember to spool your punch with the CONT option 
before you execute the EXEC, so that all of the files are transferred as 
a single spool file; for example: 


cp spool d cont library 
Then, after executing the EXEC file, close the punch: 
cp spool d nocont close 


If you pass only one argument to your CMS EXEC file, the variable &2 
is set to a null string. For example: 


cms erase 
executes as: 


ERASE PRFILE1 DOCUMENT Al 
ERASE PRFILE2 DOCUMENT A1 
ERASE PRFILE3 DOCUMENT Atl 
ERASE PRFILE4& DOCUMENT Atl 


You could also use aCMS EXEC to obtain a listing of files ona 
virtual disk. If you want, you can use one of the other LISTFILE command 
options with the EXEC option to get more information about the files 
listed. For example: 


listfile * * a (exec date 
produces a CMS EXEC that contains, in addition to the filenane, 
filetype, and filemode of each file listed, the file format and size, 
and date information. You can then use the PRINT command to obtain a 
printed copy: 


print cms exec 
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Before printing this file, you may want to use the SORT command to 
sort the list into alphabetic order by filename, by filetype, or both; 
for example: 


sort cms exec a cmssort exec a 
When you are prompted to enter sort fields, you can enter: 
1 25 


The file CMSSORT EXEC that is created contains a completely alphabetical 
list. 


MODIFYING CMS EXECS 


A CMS EXEC is like any other CMS file; you can edit it, erase it, rename 
it, or change it. If you have created it to catalog a particular group 
of files, you might want to rename it; each time you use the LISTFILE 
command with the EXEC option a CMS EXEC is created, and any old CMS EXEC 
is erased. To rename it, you can use the CMS RENAME command, or, if you 
are editing it, you can rename it when you file it: 


edit cms exec 
input &control off 
file prfile exec 


You might also want to edit a CMS EXEC to provide it with more 
humeric variables; for example: 


edit cms exec 

input &control off 

input cp spool printer class s cont 
change /al/al &3 &4 &5 &6/ * 


input cp spool printer nocont 
input cp close printer 

file prfile exec 

prfile print % (cc 


When this EXEC is executed, the variable &1 is substituted with PRINT, 
the variable &2 is set to a null string (the special character 4% 
indicates that you are not passing an argument to it), and &3 and &4 are 
set to the PRINT command option (CC, so that the files in the EXEC print 
with carriage control. 


The substitution goes as follows: 


a a aa aa ERT RR SD iC TEESE | 
| &1 | &2 {| &3 | &4 | 
| PRINT | null I ¢ | cc | 


eee ee a eae eee eee eee ee ee eS | 


The CP commands that are inserted ensure that the files print 
as a Single spool file, and not individually. 
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Summary of the CMS EXEC Language Facilities 


The CMS EXEC processor, or interpreter, recognizes keywords that begin 
with the special character ampersand (&). Keywords may indicate: 


Control statements 
Built-in functions 
Special variables 
Arguments 


You may also define your own variables in an EXEC file; the CMS EXEC 
interpreter can process them as long as they begin with an ampersand. 
The following pages briefly discuss the kinds of things you can do with 
an EXEC, introduce you to the control statements, built-in functions, 
and special variables, and give some examples of how to use the CMS EXEC 
processor. If you want more information on writing EXEC procedures, see 
"Part 3. Learning To Use EXECs." For specific information on the format 
and usage rules for any EXEC statement or variable, consult the VM/SP 
CMS Command and Macro Reference. 


In general the following rules apply to entering lines into an EXEC 
procedure: 


1. Most input lines (with a few exceptions) are scanned during 
execution of the EXEC. Every word on a line is padded or truncated 
to fit into an eight-character "token." So, for example, if you 
enter the EXEC control statement: 


&type today is wednesday 
when this EXEC is executed, the line is displayed at your terminal: 
TODAY IS WEDNESDA 


The lines that are not tokenized are those that begin with an * 
(and are considered comments), and those that follow an &BEGEMSG, 
&BEGPUNCH, &BEGSTACK, or &BEGTYPE control statement, up to an &END 
statement. 


2. You can enter input lines beginning in any column. The only time 
that you must enter an EXEC line beginning in column 1 is when you 
are using the &END control statement to terminate a series of lines 
being punched, stacked, or typed. 


ARGUMENTS AND VARIABLES 


Most EXEC processing is contingent on the value of variable expressions. 
A variable expression in an EXEC is a symbol that begins with an 
ampersand (&). When the EXEC interpreter processes a line and 
encounters a variable symbol, it substitutes the variable with a 
predefined value, if the symbol has been defined. Symbols can be 
defined in three ways: (1) when passed as arguments to the EXEC, (2) by 
assignment statements, (3) interactively, as a result of a &READ ARGS or 
&READ VARS control statement. 


You can pass arguments to EXEC files when you invoke them. Each 
argument you enter is assigned a variable name: the first argument is 
&1, the second is &2, the third is 6&3, and so on. You can assign values 
for up to 30 variables this way. For example, if an EXEC is invoked: 
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scan alpha 2 notype print 


the variable &1 has a value of ALPHA, the variable &2 has a value of 2, 
&3 is NOTYPE and &4 is PRINT. -These values remain in effect until you 
change then. 


You can test the arguments passed in several ways. The special 
variable SINDEX contains the number of arguments received. Using the 
example SCAN ALPHA 2 NOTYPE PRINT, the statement: 


SIF GINDEX EQ 4 &GOTO -SET 


would be true, since four arguments were entered, so a branch to the 
label -SET is taken. 


You can change the values of arguments or assign values using the 
SARGS control statement. For example: 


SIF SINDEX EQ 0 GARGS ABC 


assigns the values A, B, and C to the variables &1, &2, and &3 when the 
EXEC is invoked without any arguments. 


Use the &READ ARGS control statement to enter arguments 
interactively. For example, if your EXEC file contains the line: 


&READ ARGS 


when this line is executed, the EXEC issues a read to your virtual 
machine so that you can enter up to 30 arguments, to be assigned to the 
variables &1, &2, and So on. 


The words that form an executable statement are searched for the names 
of EXEC variables. These variables are replaced by their values. This 
is done according to the following steps: 


1. Each word is inspected for ampersands, starting with the rightmost 
character of the word and proceeding to the left. 


2. If an ampersand is found, then it, with the rest of the word to the 
right, is taken as the name of an EXEC variable and replaced (in 
the word) by its value. This may increase or decrease the length 
of the word. Initially, all variables have a null value, except: 


a. the variables that represent the EXEC control words and 
predefined functions, that are initialized to their own names 
(for example, the value of "SIF" is "E&IF"); and 


b. the EXEC arguments, and the other predefined variables. 


3. Inspection resumes at the next character to the left, and the 
procedure is repeated from step 2 above, until the word is 
exhausted. 


ASSIGNMENT STATEMENTS 


User-defined variable names begin with an ampersand (&) and contain up 
to seven additional characters. These variables can contain numeric or 
alphameric data. You define and initialize EXEC variables in assignment 
Statements. In an assignment statement, the first data item starts with 
an ampersand (&) and the second data item is an equal sign (=). The 
value of the expression on the right side of the equal sign is assigned 
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to the variable named on the left of the equal Sign. For example; 
SA = 35 


is an assignment statement that assigns the numeric value 35 to the 
variable symbol &A. A subseguent assignment statement might be: 


&B = &A + 10 


After this assignment statement executes, the value of &B would he 35 
plus 10, or 45. 


You can use the &READ control statement to assign variable names 
interactively. For example, when the statement: 


GSREAD VARS &NAME SAGE 


is executed, the EXEC issues -a read to your virtual machine, and you can 
enter a line of data. The first two words, or tokens, you enter are 
assigned to the variable symbols &NAME and &AGE, respectively. 


Note: The data item immediately following the target of an assignment 
statement must be an equal sign (=) and not an EXEC variable that has 
the value of an equal sign. Conversely, if an egual sign is to be the 
first data item following an EXEC control word, then it must be 
specified as an EXEC variable that has the value of an equal sign and 
not aS an equal sign; otherwise, the statement is interpreted as an 
assignment statement and the control word is thereafter treated asa 
variable. 


Null Variables 


If you use a variable name that has not been defined, the variable 
symbol is set to a null string by the EXEC processor when the statement 
is executed. For example, if you have entered only two arguments on the 
EXEC command line, then the statement: 


SIF &3 EQ CONT SERROR SCONTINUE 
is interpreted: 

GIF EQ CONT GSERROR SCONTINUE 
SERROR and &CONTINUE are recognized by EXEC as control statements. 
Since &3 is undefined, however, it is replaced by blanks and the 
resulting line produces an error during EXEC processing. You can 
prevent the error, and allow for null arguments or variables, by 
concatenating some other character with the variable. A period is used 
most frequently: 

SIF .&3 EQ .~CONT SERROR SCONTINUE 
If 6&3 is undefined when this line is scanned, the result is: 


SIF . EQ .CONT SERROR S&CONTINUE 


which is a valid control statement line. 
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BUILT-IN FUNCTIONS AND SPECIAL VARIABLES 


The EXEC built-in functions are similar to those of higher-level 
languages. You can use the EXEC built-in functions to define variable 
symbols in an EXEC procedure. 


Figure 10 summarizes the built-in functions. It shows, given the 
variable 6&A, the values resulting ina variable &B when a built-in 
function is used to assign its value. Notice that all of the built-in 
functions are used on the right-hand side of assignment statements. Only 
the SLITERAL built-in function can be used in control statements; for 
example: 


STYPE GSLITERAL &A 


ee ee ae Sm eS eG ee en ge Oe Cpe ET eS SE Oe OSS ee ee ag ee 


| Function | Usage | Example | &B | 
i l 
| l [| 6A = 123 | | 
| &CONCAT | Concatenates tokens intoa | | | 
| | single token. | &B = &CONCAT &A 55 | 12355] 
| SDATATYPE | Assigns the data type (NUM | | | 
| | or CHAR) to the variable. | &B = SDATATYPE &A | NUM | 
| & LENGTH | Assigns the length of a | | [ 
| | token to a variable. | &B = &LENGTH &A | 3 | 
| SLITERAL | Prohibits substitution of a | | | 
| | variable symbol. | &B = &LITERAL &A | SA | 
{ &SUBSTR | Extracts a character string | | | 
| | from a token. | &B = &SUBSTR &A 2 2 | 23 | 


Figure 10. Summary of CMS EXEC Built—in Functions 


FLOW CONTROL IN AN EXEC 


An EXEC is processed line by line: if a statement is encountered that 
passes control to another line in the procedure, execution continues 
there and each line is, again, executed sequentially. You can pass 
control with an &GOTO control statement: 

&GOTO -BEGIN 


where -BEGIN is a label. All labels in EXEC files must begin with a 
hyphen, and must be the first token on a line. For example: 


-LOOP 


A label may have control statements or commands following it; for 
example: 


~HERE &CONTINUE 


which indicates that the processing is to continue with the next line, 
Or: 


-END &EXIT 


The &SEXIT control statement indicates that the EXEC processor should 
terminate execution of the EXEC and return control to CMS. You can also 
specify a return code on the &EXIT control statement: 
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EEXIT 6 


results in a "(00006)" following the "R" in the CMS ready message. If 
you invoke a CMS command from the EXEC, you can specify that the return 
code from the CMS command be used: 


EEXIT GRETCODE 


Since the &RETCODE special variable is set after each CMS command 
that is executed, you can test it after any command to decide whether 
you want execution to end. For example, you could use the 6&IF control 
statement to test it: 


SIF &RETCODE NE 0 &EXIT &SRETCODE 


"GEXIT SRETCODE" places the value of the CMS return code in the CMS 
ready message. You could place a line similar to the above following 
each of your CMS command lines, or you could use the 6&ERROR control 
statement, that will cause an exit as soon aS an error is encountered: 


GSERROR &EXIT &RETCODE 


or you could use the &ERROR control statement to transfer control to 
some other part of your EXEC: 


GERROR &GOTO -CHECK 


-CHECK 


Another way to transfer control to another line is to use the &SKIP 
control statement: 


&SKIP 10 


transfers control to a line that is 10 lines below the &SKIP line. You 
can transfer control above the current line as well: 


GIF &X NE &Y &SKIP -3 


Transferring control with &SKIP is faster, when an EXEC is executing, 
than it is with &GOTO, but modifying your EXEC files becomes nore 
difficult, particularly when you add or delete many lines. 


You can use combinations of &IF, &GOTO, and &SKIP to set up loops in 
an EXEC. For example: 


&X = 1 

EIF &X = 4 &EGOTO -ENDPRT 
PRINT FILE&X TEST A 

&X = &X + 1 

&SKIP -3 

-ENDPRT 


Or, you can use the &LOOP control statement: 
&X = 1 
&LOOP 2 &X > 3 
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PRINT FILE&X TEST 
&X = &X + 1 
-~ENDPRT 


In both of these examples, a loop is established to print the files 
FILE1 TEST, FILE2 TEST, and FILE3 TEST. &X is initialized with a value 
of 1 andthen incremented within the loop. The loop executes until the 
value of &X is greater than 3. AS soon as this condition is met, control 
is passed to the label —-ENDPRT. 


COMPARING VARIABLE SYMBOLS AND CONSTANTS 


In an EXEC, you can test whether a certain condition is true, and then 
perform some function based on the decision. Some examples have already 
appeared in this section, such as: 


&LOOP 3 &X EQ &Y 
In this example, the value of the variable &K is tested for an equal 
comparison with the value of the variable &Y. The loop is executed uatil 
the condition (&X equal to &Y) is true. 


The logical comparisons you can make are: 


Condition Mnemonic Symbol 
equal EQ = 
not equal NE a= 
greater than GT > 
less than LT < 
greater than 

or equal to GE >= 
less than or 

equal to LE <= 


When you are testing a condition in an EXEC file, you can use either the 
mnemonic or the symbol to represent the condition: 


SIF &A LT &B &EGOTO —-NEXT 
is the same as: 


SIF G&A < &B &GOTO -NEXT 


DOING I/O WITH AN EXEC 


You can communicate with your terminal using the &TYPE and &READ control 
statements. Use &TYPE to display a line at your terminal: 


ETYPE ASMBLNG &1 ASSEMBLE 


When this line is processed, if the variable &1 has a value of PROG1, 
the line is displayed as: 


ASMBLNG PROG1 ASSEMBLE 
Use the G&READ control statement when you want to be able to enter 
data, variables, or control statements into your EXEC file while it is 
executing. If you use it with an &TYPE statement, for example: 


STYPE DO YOU WANT TO CONTINUE ? 
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SREAD VARS &ANS 


you could test the variable &ANS in your EXEC to find out how processing 
is to continue. 


The &BEGTYPE control statement can be followed by a sequence of lines 
you want to be displayed at the terminal. For exauple, if you want to 
display ten lines of data, instead of using ten &TYPE control 
statements, you could use: 


&BEGTYPE 
linet 
line2 


line10 
& END 


The &END control statement indicates the end of the lines’ to be typed. 
You can also use the &SBEGTYPE control statement when you want to type a 
line that contains a word with more than eight characters in it; for 
example: 


&BEGTYPE 


TODAY IS WEDNESDAY 
& END 


The EXEC interpreter, however, does not perform substitutions on lines 
entered this way. The lines: 


SA = DOG 
&BEGTYPE 


MY SA IS NAMED FIDDLEFADDLE 
& END 


result in the display: 

MY &A IS NAMED FIDDLEFADDLE 
You must use the &TYPE statement when you want to display variable data; 
you must use the &BEGTYPE control statement to display words with more 


than eight characters. 


To type null or blank lines at your terminal (to make output 
readable, for example), you can use the &SPACE control statement: 


ESPACE 5 


Using Your Virtual Card Punc 


You can punch lines of tokens into your virtual card punch with the 
&PUNCH control statement: 


S&PUNCH &NAME &TOTAL 


When you want to punch more than one line of data, or a line that 
contains a word of more than eight characters in it, you should use the 
&BEGPUNCH control statement preceding the lines you want to punch, and 
follow them with an E&END' statement. The EXEC processor does not 
interpret these lines, however, so any variable symbols you’ enter on 
these lines are not substituted. 
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When you punch lines from an EXEC procedure what you are actually 
doing is creating a file in your virtual card punch. To release the 
file for processing, you must close the punch: 


cp close punch 


The destination of the file depends on how you have spooled your punch. 
If you have spooled it to yourself, the file is placed in your virtual 
card reader, and you can read it onto a virtual disk using the READCARD 
command. 


Stacking Lines 


The EXEC control statements &STACK and 6&BEGSTACK allow you to stack 
lines in your program stack, to be executed aS soon as a read occurs in 
your virtual machine. Stacking is useful when you use commands that 
require responses, for example, the SORT command: 


S&STACK 1 20 
SORT INFILE FILE A OUTFILE FILE A 


When the SORT command is executed, a prompting message is issued, the 
virtual machine read occurs, and the response that you have stacked is 
read. If you do not stack a response to this command, your EXEC does 
not continue processing until you enter the response from your terminal. 


In the above example of the SORT command, you can suppress the 
prompting message by issuing either the SET CMSTYPE HT command or &STACK 
HT immediately before the SORT command. Restore normal terminal 
operations by placing either a SET CMSTYPE RT command or &STACK RT after 
the SORT command. 


Stacking is useful in creating edit macros or in editing files from 
EXEC procedures. 


Note: &STACK HT and SET CMSTYPE HT create the same effect when 
interpreted by the CMS EXEC processor. Similarly, &STACK RT and SET 
CMSTYPE RT are equivalent for the EXEC 2 processor. However, when using 
EXEC 2, the commands &STACK HT and &STACK RT will cause the characters 
"HT" and "RT" to be placed in the program stack but will not affect the 
console output. Unless these characters are part of a program or 
cleared from the stack, you will receive an “UNKNOWN CP/CMS COMMAND" 
error message when they are read from the stack. 


MONITORING EXEC PROCEDURES 


Two EXEC control statements, E& CONTROL and 6&TIME, control how auch 
information is displayed at your terminal while your EXEC file is 
executing. This display is called an execution summary. 


Since you do not usually receive a CMS ready message after the 
execution of each CMS command in an EXEC, you do not receive the timing 
information that is provided with the ready message. If you want this 
tining information to appear, you can specify: 

STIME ON 


Or you can type the CPU times at particular places by using: 
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&TIME TYPE 
The S&CONTROL control statement allows you to specify whether certain 
lines or types of information are displayed during execution. BY 
default, CP and CMS commands are displayed before they are executed. If 
you do not wish to see them displayed, you can specify: 
SCONTROL OFF 
You might find it useful, when you are debugging your EXECs, to use: 
G&CONTROL ALL 
When you use this form, all EXEC statements, as well as all CP and CMS 


commands, are displayed and you can see the variable substitutions being 
performed and the branches being taken in a procedure. 


The EXEC 2 Processor 


The EXEC 2 processor handles EXEC 2 programs. These EXEC 2 programs and 
processing are similar to CMS EXEC programs and processing. 


EXEC 2 differs from CMS EXEC in the following ways: 


1. There is no 8-byte token restriction. Statements are composed of 
"words! of up to 255 characters each. 


2. Commands may be issued from EXEC 2 either to CMS or to specified 
*"subcommand! environments, for example the System Product editor. 


3. EXEC 2 has extended string manipulation functions. 

4. EXEC 2 has arithmetic functions for multiplication and division. 
5. EXEC 2 has extended debugging facilities. 

6. EXEC 2 supports user defined functions and subroutines. 

7. |§EXEC 2 allows CMS user programs to manipulate EXEC 2 variables. 


In addition, the EXEC 2 interpreter is used by the System Product Editor 
for edit macro processing support. 


RELATIONSHIP OF EXEC AND EXEC 2 


EXEC 2 does not support all language keywords and syntax of the CMS EXEC 
processor. EXEC 2 coexists with the CMS EXEC processor progran. 


EXEC programs written for the CMS EXEC processor will continue to 
execute correctly with no user modifications. To run CMS EXEC programs 
as EXEC 2 programs, you must convert the EXEC programs to EXEC 2 
programs. See the publication VWM/SP EXEC 2 Reference for information on 
conversion. 


You may not use CMS EXEC language statements in an EXEC to be 
interpreted by the EXEC 2 processor, nor EXEC 2 language statements in 
an EXEC to be interpreted by the CMS EXEC processor. However, you may 
call an EXEC 2 procedure from a CMS EXEC procedure, and vice versa. 
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To allow greater user flexibility with EXEC 2, automatic cleanup of 
an active OS or VSAM environment is not invoked at command completion as 
it is in the CMS EXEC processor. It is the programmer's responsibility 
to ensure that STRINIT, OS RESET, and/or VSAM cleanup functions are 
invoked when needed. VSAM cleanup can be invoked explicitly from the 
EXEC 2 EXEC by issuing 'DMSVSR' as a command. Any CMS EXEC invoked may 
reset the CMS/VSAM environment at the completion of any CMS command. A 
STRINIT macro may be issued from the user program to initialize user 
Storage. STRINIT resets OSFLAGS and purges STAE and SPIE exits, if 
RELPAGE is on. If GENMOD was run with the STR option for a nodule that 
is loaded, then STRINIT is issued for that module. 


INVOKING EXEC 2 


EXEC 2 programs may reside in EXEC files (with a filetype of EXEC), and 
can be invoked by the EXEC 2 interpreter. The EXEC 2 interpreter is 
invoked in the same way the CMS EXEC interpreter is invoked. 


For both CMS EXEC and EXEC 2 files with a filetype of EXEC, CMS 
examines the first statement of the EXEC file to determine which EXEC 
processor must handle it. If the first statement of the EXEC is 
STRACE, CMS calls the EXEC 2 processor to handle it. If the first 
statement is not &TRACE, CMS calls the EXEC processor to handle it. 


Note: The &TRACE statement does not have to be the first statement in a 


file if the file does not have a filetype of EXEC (if the EXEC is 
invoked by an SVC 202). 


The CMS commands intended to be issued from EXEC 2 EXECS are: 


e EXECIO - Manages movement of lines between virtual devices and the 
program stack. Also causes execution of CP commands and recovers 
resulting output. 


e GLOBALV - Used to set, maintain, and retrieve a collection of named 
variables. 


The whesE CMS Command and Macro Reference contains command format and 
operand descriptions as well as extended usage notes and examples of how 
these commands may be used within EXEC 2 EXECs. 


ATTRIBUTES OF EXEC 2 FILES 


EXEC 2 files can have any filename. EXEC 2 files have the filetype EXEC 
for files that are invoked from CMS command mode, and the filetype XEDIT 
for files used as System Product Editor macros. 


EXEC 2 files can be either ‘Ff or 'tV*" format. The maximun line 
length for lines read from the console is 130; for lines read from the 
stack it is 255. 


For complete information about EXEC 2, see the publication VM/SP EXEC 
2 Reference. 
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Summary of CMS EXEC Control Statements and Special Variables 


Figures 11 and 12 summarize CMS 


variables. 
Control Statement 
S&variable = (string 
ae 
function 
X™'xxxxxx 


&ARGS [argl1 [arg2 ...[arg30]]] 


&BEGEMSG [ALL] 
linet 
line2 


& END 


&BEGPUNCH [ALL] 
linet 
line2 


& END 


& BEGSTACK | 
linet | LIFO 
line2 L 


SEND 


SBEGTYPE [ALL] 
line1 
line2 


& END 


SCONTINUE 
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EXEC control statements and special 


| Function 


[Assigns a value to the symbol 
| specified by &variable; the 
|equal sign must be preceded 
Jand followed by a blank. 


|Redefines the variable symbols 
{&1, &2... with the values of 
J*argi*, ‘arg2', .~.., and re— 
[sets the variable &INDEX. 


[Displays the following lines 
[as CMS error messages, without 
[scanning then. 

| 
[ 
| 


l 

A 

{ 

[ 

! 

{ 

{ 

[ 

| 

; 

[ 

I 

[ 

[ 

[ 

[ 

{ 

[ 

{ 

| Punches the following lines { 
[in the virtual card punch, | 
[without scanning then. | 
| | 
{ i 
l | 
i 

| Stacks the following lines | 
i 

| 

l 

[ 

[ 

{ 

{ 

[ 

{ 

I 

A 

[ 

; 

| 

I 

l 

y 


{in the console input buffer, 
|without scanning then. 


| Displays the following lines 
jat the console, without 
{scanning then. 

I 
[ 
; 
| Provides a tEranch address for 


[|&ERROR, &GOTO, and other con— 
[ditional branching statements. 


ee 
Figure 11. Summary of CMS EXEC Control Statements (Part 1 of 3) 
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Control Statement | Function 


|Loops through the following n 
&LOOP (n m Jlines, or down to (and includ— 
label condition} 


jing) the line at label, for 
jm times, or until the 
|condition is satisfied. 


S&PUNCH [tok1 [...tokn]] | Punches the specified tokens 
|to your virtual card punch. 


| | 
t l 
| SCONTROL |Sets, until further notice, | 
| ir 1 6 af 1 Ff + jthe characteristics of the | 
| {OFF | [MSG [| |TIME | |PACK | {execution summary of the EXEC, | 
| [ERROR] |NOMSG| |NOTIME| |NOPACK| |which is displayed at the | 
| ICNS | & jot Jot J | console. | 
{ {ALL | l { 
i , } 
| SEMSG mmunnns [tok1 [...tokn]] | Displays a line of tokens | 
I jas a CHS error message. { 
i l 
| SEND | Terminates a series of lines | 
| | following an &BEGEMSG, | 
| |&BEGPUNCH, &BEGSTACK, or | 
| |&BEGTYPE control statement. | 
[ [ 
[ r 4 | Executes the specified | 
| SERROR jexecutable—statepent| {statement whenever a CMS | 
| [&ECONTINUE [ |command returns a nonzero | 
| L 4 |return code. 
I i 
| cr 1 | Exits from the EXEC file with | 
| &SEXIT |return—code| {the given return code. I 
; { 9 I [ ; 
; . 7 | | 
| —————_—_-—-— nnn eee ne nnn — — = ee | 
{| &GOTO ( TOP [Transfers control to the top | 
| | Hinenanber| jof the EXEC file, to the given| 
| —label Jline, or to the line starting | 
{ {with the given label. | 
I 4 
| SHEX e {Turns on or off hexadecimal | 
| oeel | conversion. | 
I { 
| SIF ( tokT EQ tok2) executable— | Executes the specified | 
I &S NE &$ statement | statement if the condition is | 
| &* LT &* |satisfied. | 
[ LE | | 
| GT ; | 
; GE | | 
I a i | 
[ = | [ 
[ < { [ 
[ l | 
| I l 
H l | 
I I 
| i 
; i 
[ | 
| { 
[ | 
i ; 
| | 
l 1 


Figure 11. Summary of CMS EXEC Control Statements (Part 2 of 3) 
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CS eS Se 
Control Statement | Function 


1 jReads lines from the terminal 
jn | jor from the cc"sole stack. 

{1 | {ARGS assigns ‘he tokens read 
| ARGS | Jto the variables &1, &2 ... 
[VARS [&var1 [...&var17]]| {VARS assigns the tokens read 
L 4 jto the specified variable 


[ { 
l | 
l i 
[ | 
| l 
[ l 
l [ 
f | 
| {|symbols. | 
l l 
| r 1 [Transfers control forward or | 
| ESKIP |n | | backward a specified number | 
| | 1 | {of lines. | 
[ . 2 l [ 
| | 
| r 1 | Displays blank lines at the | 
| &6SPACE | n | | terminal. | 
l | 1 | l l 
| 4 4 l l 
| ee 
{ cr 1 7 {Stacks a line in the terminal | 
| &STACK [FIFO] |tok1 [... tokn]|] [input stack. | 
| [LIFO| |HT l [ l 
| L 4 [RT l | { 
| E = l [ 
I i 
| r 1 | Displays timing information | 
| &TIME |ON | |following the execution of | 
| |OFF | |CMS commands. | 
| | RESET | [ [ 
| (TYPE | | l 
| L J | l 
I l 
| &STYPE [tok1 [...tokn]] {Displays a line at the | 
| | 


jterninal. 
a a ee 


Figure 11. Summary of CMS EXEC Control Statements (Part 3 of 3) 
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E&EDISKX 


EDISK* 


&DISK? 


&GLOBAL 


&GLOBALn 


GINDEX 


E&ELINENUM 


GEREADFLAG 


&RETCODE 


&STYPEFLAG 


Variable | 
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Usage 


Arguments passed to an EFXEC are assigned to 
the variables &1 through &30. 


Test whether all (&*) or any (&$) of the 
arguments passed to EXEC have a particular 
value. 


Indicates whether the disk access at mode ‘x! 
is a CMS OS, or DOS disk, or not accessed 
(CMS, OS, DOS, or NA). 


Contains the mode letter of the first read/write 


disk in the CMS search order, or NONE if no 
read/write disk is accessed. 


Contains the mode letter of the read/write disk 


with the most available space or NONE, if no 
read/write disk is accessed. 


Indicates whether or not the CMS/DOS environment 


is active (ON or OFF). 


Contains the filename of the EXEC file currently 


being executed. 


Has a value ranging from 1 to 19, to indicate 


the recursion (nesting) level of the EXEC that 


is currently executing. 


The variables &GLOBAL1 through &GLOBAL9I can 
contain integral numeric values, and can he 
passed among different recursion levels. If 
not explicitly set, the variable will have a 
value of 1. 


Contains the number of arguments passed to 

the EXEC on the command line or the number of 
arguments entered as a result of an &ARGS or 
&READ ARGS control statement. 


Contains the current line number in the EXEC. 
Indicates whether (STACK) or not (CONSOLE) 


there are lines stacked in the terminal input 
buffer (console stack). 


Contains the return code from the most recently 


executed CMS command. 


Indicates whether (RT) or not (HT) output is 
being displayed at the console. 


Contains the name of the EXEC file. 
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Variables are assigned values by EXEC but you may modify 
You may not modify these variakles. 
You may asSign a vaiue to this variable put it is reset at the 
completion of each CS command. 


12. CMS EXEC Special Variakles 
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User 


User 


User 


User 


EXEC 


EXEC 


User 


EXEC 


EXEC 


EXEC 


CMS 


then. 
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Section 7. Using Real Printers, Punches, Readers, and Tapes 


CMS Unit Record Device Support 


CMS supports one virtual card reader at address 00C, one virtual card 
punch at address 00D, and one virtual printer at address O0E. When you 
invoke a CMS command or execute a program that uses one of these unit 
record devices, the device nust be attached at the virtual address 
indicated. 


USING THE CP SPOOLING SYSTEM 


Any output that you direct to your virtual card printer or punch, or any 
output you receive through your card reader, is controlled by the 
spooling facilities of the control program (CP). Each output unit is 
known to CP as a spool file, and is queued for processing with the spool 
files of other users on the system. Ultimately, a spooled printer file 
or a spooled punch file may be released to a real printer or card punch 
for printing or punching. 


The final disposition of a unit record spool file depends on the 
spooling characteristics of your virtual unit record devices, which you 
can alter with the CP command SPOOL. To find out the current 
characteristics of your unit record devices you can issue the command: 


cp query ur 


See Figure 13 for an example of the response you will receive fron 
issuing this command. 


CL A NOCONT NOHOLD EOF READY 
CL A NOCONT NOHOLD COPY O01 READY FORM STANDARD 
FOR CMSGDE DIST 2647-706 


CL A NOCONT NOHOLD COPY 01 READY FORM STANDARD 
FOR CMSGDE DIST 2G47-706 FLASHC 000 


RUNNING 


Figure 13. CP Query Unit Record Response 
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Some of the characteristics, and ways you can modify the ‘cp guery 
ucr* command are discussed below. When you use the SPOOL command to 
control a virtual unit record device, you do not change the status of 
spool files that already exist, but rather set the characteristics for 
subsequent output. For information on modifying existing spool files, 
see "Altering Spool Files," below. 


CLASS (CL): Spool files, in the CP spool file queue, are grouped 
according to class, and all files of a particular class may be processed 
together, or directed to the same real output device. The default 
values for your virtual machine are set in your VM/SP directory entry, 
and are probably the standard classes for your installation. 


You may need, however, to change the class of a device if you want a 
particular type of output, or some special handling for a_ spool file. 
For example, if you are printing an output file that reguires special 
forms, and your installation expects that output to be spooled class fY, 
issue the command: 


cp spool printer class y 


All subsequent printed output directed to your printer at virtual 
address OOE (all CMS output) is processed as class Y. 


HOLD: If you place a HOLD on your printer or punch, any files that you 
print or punch are not released to the control program's spooling queue 
until you specifically alter the hold status. By placing your output 
spool files in a hold status, you can select which files you print or 
punch, and you can purge duplicate or unwanted files. To place printer 
and punch output files in a hold status issue the commands: 


cp spool printer hold 
Cp spool punch hold 


Note: When you issue a SPOOL command for a unit record device, you can 
refer to it by its virtual address, as well as by its generic device 
type (for example, CP SPOCL E HOLD). 


When you have placed a hold status on printer or punch files and you 
produce an output file for one of these devices, CP sends you a message 
to remind you that you have placed the file in a hold: 

PRT FILE xxxx FOR userid COPY xx HOLD 
If, however, you have issued the command: 
cp set asg off 
then you do not receive the message. 
When you place a reader file in a hold status, then the file remains 


in the card reader until you remove the hold status and read it, or you 
purge it. 


COPY: If you want multiple copies of a spool file, you should use the 
COPY operand of the SPOOL command: 

cp spool printer copy 10 
If you enter this command, then all subsequent printer files that you 


produce are each printed 10 times, until you change the COPY attribute 
of your printer. 
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FOR: You can spool printed or punched output under another userid's name 
by using the FOR operand of the SPOOL command. For example, if you 
enter; 


Cp spool printer for charlie 


Then, all subsequent printer files that you produce have, on the output 
separator page, the userid CHARLIE and the distribution code for that 
user. The spool file is then under the control of that user, and you 
cannot alter it further. 


CONT, NOCONT: You can print or punch many sg&pool files, but have then 
print or punch as one continuous spool file if you use the CONT operand 
on the SPOOL command. For example, if you issue the following sequence 
of commands: 


cp spool punch cont to brown 
punch asm1 assemble 

punch asm2 assemble 

punch asm3 assemble 

Cp spool punch nocont 

cp close punch 


Then, the three files ASM1 ASSEMBLE, ASM2 ASSEMBLE, and ASM3 ASSEMBLE, 
are punched to user BROKN as a single spool file. When user BROWN reads 
this file onto a disk, however, CMS creates separate disk files. 


TO: When you spool your printer or punch to another userid, all output 
from that device is transferred to the virtual card reader of the userid 
you specify. When you are punching a CMS disk file, as in the example 
above, you should use the TO operand of the SPOOL command to specify the 


destination of the punch file. 


You can also use this operand to place output in your own virtual 
card reader by using the * operand: 


cp spool printer to * 


After you enter this command, subsequent printed output is placed in 
your virtual card reader. You might use this technique as an alternative 
way of preventing a printer file from printing, or, if you choose to 
read the file onto disk from your reader, of creating a disk file fron 
printer output. 


Similarly, if you are creating punched output in a program and you 
want to examine the output during testing, you could enter: 


cp spool punch to * 


so that you do not punch any real cards or transfer a virtual punch file 
to another user. 


ALTERING SPOOL FILES 


After you have requested that VM/SP print or punch a file, or after you 
have received a file in your virtual card reader and before the file is 
actually printed, punched, or read, you can alter some of its 
characteristics, change its destination, or delete it altogether. 


Every spool file in the VM/SP system has a unigue four-digit number 
from 1 to 9900 assigned to it, called a spoolid. You can use the spoolid 
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of a file to identify it when you want to do something to it. You can 
also change a group of files, by specifying that all files of a 
particular class be altered in some way, or you can manipulate all of 
your spool files for a certain device at the same time. 


The CP commands that allow you’ to manifulate spool files are CHANGE, 
ORDER, PURGE, and TRANSFER. In addition, you can use the CP QUERY 
command to list the status and characteristics of spool files associated 
with your userid. 


When you use any of these commands to reference spool files of a 
particular device, you have the choice of referring to the files by 
class or by spoolid. You can also specify ALL. For example, if you 
enter the command: 


cp query printer all 


you might see the display: 


CPIGINID FILE CLASS RECDS CPY HOLD DATE TIME NAME TYPE DIST 
CMSUG 0142 K PRT 000178 02 USER 04/17 07:58:48 SCHED SCRIPT BIN706 
CMSUG 0180 1 PRT 002021 01 NONE 04/717 08:02:26 TESTFILE SCRIPT BIN706 


Until any of these files are processed, or in the case of files in the 
hold status, until they are released, you can change the spool file name 
and spool file type (this information appears on the first page or first 
card of output), the distribution code, the number of copies, the class, 
or the hold status, using the CP CHANGE command. For example: 


cp change printer all nohold 
changes all printer files that are in a hold status to a nohold status. 


The CP CHANGE command can also change the spooling class, distribution 
code, and so on. 


If you decide that you do not want to print a particular printer 
file, you can delete it with the CP PURGE command: 


cp purge printer 7615 
After you have punched a file to some other user, you cannot change 


its characteristics or delete it unless you restore it to your own 
Virtual reader. You can do this with the TRANSFER command: 


cp transfer all from usera 


This command returns to your virtual card reader all punch files that 
you spooled to USERA's virtual card reader. 


You can determine, for your reader or printer files, in what order 
they should be read or printed. If you issue the command: 


cp order printer 8195 6547 


Then, the file with spoolid of 8195 is printed before the file with a 
spoolid of 6547. 


The CP spooling system is very flexible, and can be a useful tool, if 
you understand and use it rfroperly. The VM/SP CP Command Reference for 
General Users contains complete format and operand descriptions for the 


CP commands you can use to modify spool files. 
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USING YOUR CARD PUNCH AND CARD READER IN CMS 


The CMS READCARD command reads cards from your virtual card reader at 
address 00C. Cards can ke placed in the reader in one of two ways: 


e By reading real punched cards into the system card reader. A CP ID 
card tells the CP spooling system which virtual card reader is to 
receive the card images. 


e By transferring a file from another virtual machine. Cards are 
transferred as a result of a virtual punch or printer being spooled 
with the TO operand, or as a result of the TRANSFER command. Virtual 
card images are created with the CMS PUNCH command, or from user 
programs or EXEC procedures. 


If you have a deck of punched cards that you want read into your virtual 
machine card reader, you should punch, preceding the deck, a CP ID card: 


ID HAPPY 


If you plan to use the REALCCARD command to read this file onto a CMS 
disk, you can also punch a READ control card that specifies the filename 
and filetype you want to have assigned to the file: 


sREAD PROG6 ASSEMBLE 

Then, to read this file onto your CMS A-disk, you can enter the command: 
readcard * 

If a file named PROG6 ASSEMBLE already exists, it is replaced. 


If you do not punch a READ control card, you can specify a filenane 
and filetype on the READCARD command: 


readcard prog6 assemble ; 
If this spool file contained a READ control card, the card is not read, 
but remains in the file; if you edit the file, you can use the DELETE 
subcommand to delete it. 


If a file does not have a REAL control card, andif you do not 
specify a filename and filetype when you read the file, CMS names the 
file READCARD CMSUT1. 


If you are reading many files into the real system card reader, and 
you want to read them in as separate spool files (or you want to spool 
them to different userids), you must separate the cards and read the 
decks onto disk individually. The CP system, after reading an ID card, 
continues reading until it reaches a physical end of file. 


Using Your Virtual Card Punch 


When you use the CMS PUNCH command to punch a spool file, a READ control 
card is punched to precede the deck, so that it can be read with the 
READCARD command. If you do not wish to punch a READ control card (also 
referred to as a header card), you can use the NOHEADER option on the 
PUNCH command: 
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punch prog8 assemble * ( noheader 


You should use the NOHEADER option whenever you punch a file that is not 
going to be read by the READCARD command. 


The PUNCH command can only punch records of up to 80 characters in 
length. If you need to punch or to transfer to another user a file that 
has records greater than 80 characters in length, you can use the DISK 
DUMP command: 


disk dump prog9 data 


If your virtual card punch has been spooled to another user, that user 
can read this file using the DISK LOAD command: 


disk load 


Unlike the READCARD command, DISK LOAD does not allow you to specify a 
file identification for a file you are reading; the filename and 
filetype are always the same as those specified by the DISK DUMP command 
that created the spool file. 


A card file created by the DISK DUMP command can only be read onto 
disk by the DISK LOAD command. 


Using the MOVEFILE Command 


You can use the MOVEFILE command, in conjunction with the FILEDEF 
command, to place a file in your virtual card reader, or to copy a file 
from your card reader to another device. For example: 


Cp spool punch to * 

filedef punch punch 

filedef input disk coffee exec atl 
movefile input punch 


the file COFFEE EXEC A1l is punched to your virtual card punch (in 
card-image format) and spooled to your own virtual reader. 


Creating Files Using Your Reader and Punch 


Apart from the procedures shown above, that transfer whole files with 
one or two commands, there are other methods you can use to create files 
using your virtual card punch. From a program or an EXEC file, you can 
punch one line at atime to your virtual punch. Then use the CLOSE 
command to close the spool file: 


cp close punch 


Depending on how the punch was spooled (the TO setting), the virtual 
punch file is either punched or transferred to a virtual card reader. 


PUNCHING CARDS USING I/O MACROS: If you write an OS, DOS, or CMS progran 
that produces punched card outrut, you should make an appropriate file 
definition. If you are an OS user, you should use the FILEDEF command 
to define the punch as an output data device; if you are a DOS user, you 
must use the ASSGN command. If you are using the CMS PUNCHC macro, the 
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punch is assigned for you. The spooling characteristics of your virtual 
punch control the destination of the punched output. 


PUNCHING CARDS FROM AN EXEC: The EXEC facilities provide two control 
statements for punching cards: &PUNCH, which punches a single line to 
the virtual card punch, and &BEGPUNCH, which precedes a number of lines 
to be punched. You can also, in an EXEC, use the commands PUNCH and 
DISK DUMP to punch CMS files. 


Handling Tape Files in CMS 


There are a variety of tape functions that you can perform in CMS, and a 
number of commands that you can use to control tape operations or to 
read or write tape files. One of the advantages of placing files on 
tapes is portability: it is a convenient method of transferring data 
from one real computing system to another. In CMS, you can use tapes 
created under other operating systems. There are also two CMS commands, 
TAPE and DDR, that create tape files in formats unigue to CMS, that you 
can use to back up minidisks or to archive or transfer CMS files. 


Under VM/SP, virtual addresses 181 through 184 are usually reserved 
for tape devices. In most cases, you can refer to these tapes in CMS by 
using the symbolic names TAP1 through TAP4. In any event, before you 
can use a tape, you must have it mounted and attached to your virtual 
machine by the system operator. When the tape is attached, you receive 
a message. For example, if the operator attaches a tape to your virtual 
machine at virtual address 181, you receive the message: 


TAPE 181 ATTACHED 


The various types of tape files, and the commands and programs you 
can use to read or write them are: 


TAPE Command: The CMS TAPE command creates tape files from CMS disk 
files. They are in a special format, and should only be read by the CMS 
TAPE LOAD command. For examples of TAPE command operands and options, 
see "Using the CMS TAPE Command." 


TAPPDS Command: The TAPPDS command creates CMS disk files from OS or DOS 
sequential tape files, or from OS partitioned data sets. 


TAPEMAC Command: The TAPEMAC command creates CMS MACLIB files from OS 
macro libraries that were unloaded onto tape with the IEHMOVE utility 
progran. 


MOVEFILE Command: The MOVEFILE command can copy a_ sequential tape file 
onto disk ora disk file onto tape. Or, it can move files from your 
card reader to tape or from tape to your card punch. 


User Programs: You can write programs that read or write sequential tape 
files using OS, DOS, or CMS macros. 


Access Method Services: Tapes created by the EXPORT function of access 
method services can be read only using the access method services IMPORT 
function. Both the IMPORT and EXPORT functions can be accomplished in 
CMS using the AMSERV command. The access method services REPRO function 
can also be used to copy sequential tape files. 
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DDR Program: The DDR program, invoked with the CMS command DDR, dumps 
the contents of a virtual disk onto tape, and should be used to restore 
such files to disk. 


USING THE CMS TAPE COMMAND 


The CMS TAPE command provides a variety of tape handling functions. It 
allows you to selectively dump or load CMS files to and from tapes, as 
well as to position, rewind, and scan the contents of tapes. You can 
use the TAPE command to save the contents of CMS disk files, or to 
transfer them from one VM/SP system to another. The following example 
shows how to create a CMS tape with three tape files on it, each 
containing one or more CMS files, and then shows how you, or another 
user, might use the tape at a later time. 


The example is in the form of a terminal session and shows, in the 
"Terminal Display" column, the commands and responses you might see. 
System messages and responses are in uppercase, and user-entered 
commands are in lowercase. The "Comments" column provides explanations 
of the commands and responses. 


Terminal Display Comments 

TAPE 181 ATTACHED Message indicates that the tape is 
attached. 

listfile * assemble a (exec Prepare to dump all ASSEMBLE files 

R3 by using the LISTFILE command EXEC 

cms tape dump option; then execute the CMS EXEC 

TAPE DUMP PROG1 ASSEMBLE Al using TAPE and DUMP as arguments. 

DUMPING..... The TAPE command responds to each 

PROG1 ASSEMBLE Atl TAPE DUMP by printing the file 

TAPE DUMP PROG2 ASSEMBLE Al identification of the file being 

DUMPING..... dumped. 

PROG2 ASSEMBLE Al 


TAPE DUMP PROG3 ASSEMBLE Al 


TAPE DUMP PROGO ASSEMBLE Atl The last file, PROGY ASSEMBLE, is 
DUMPING..... dumped. 

PROGY ASSEMBLE A1 

R; 

tape wtn The TAPE command writes a tape mark 
R; . to indicate an end of file. 

tape dump mylib maclib a Two macro libraries are dumped, 
DUMPING..... by specifying the file identifiers. 
MYLIB MACLIB A 

R$ 


tape dump cmslib maclib * 
DUMPING..... 
CMSLIB MACLIB S2 


R$ 

tape wtn Another tape mark is written. 
R; 

tape dump mylib txtlib a A TEXT litrary is dumped. 
DUMPING..... 

MYLIB TXTLIB Al 

R; 

tape wtm 2 Two tape marks are written to 
R; indicate the end of the tape. 
tape rew The tape is rewound. 

R5 
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Terminal Display 
tape scan (eof 4 
SCANNING.... 


PROG1 ASSEMBLE Atl 
PROG2 ASSEMBLE At1 
PROG3 ASSEMBLE Atl 
PROG4Y ASSEMBLE Atl 
PROG5 ASSEMBLE A1 
PROG6 ASSEMBLE Atl 
PROG? ASSEMBLE Atl 
PROG8 ASSEMBLE A1 
PROGY ASSEMBLE At 
END-OF-FILE OR END-OF-TAPE 
MYLIB MACLIB A1 


CMSLIB MACLIB S2 
END-OF-FILE OR END-OF-TAPE 
AYLIB TXTLIB A1 
END-OF-FILE OR END-OF-TAPE 
END-OF-FILE OR END-OF-TAPE 


R; 

#cp det 181 

TAPE 181 DETACHED 
KH HK KKK & 

* 


* The tape created above is going 


* 
HK HK KK KK KH 


TAPE 181 ATTACHED 


tape load prog4 assemble 
LOADING..... 

PROG4 ASSEMBLE Atl 

R5 


tape scan 
SCANNING.... 


PROGS5 ASSEMBLE A1 

PROG6 ASSEMBLE A1 

PROG7 ASSEMBLE A1 

PROGS ASSEMBLE A1 
END-OF-FILE OR END-OF-TAPE 
R; 


tape scan 

SCANNING.... 

MYLIB MACLIB Al 
CMSLIB MACLIB S2 
END-OF-FILE OR END-OF-TAPE 
R3 

tape bsf 2 

R; 


tape fsf 


R; 

tape load (eof 2 
LOADING..... 

MYLIB MACLIB Al 
CMSLIB MACLIB A2 
END-OF-FILE OR END-OF-TAPE 


MYLIB TXTLIB Al 
END-OF-FILE OR END-OF-TAPE 
R3 


#cp detach 181 
TAPE 181 DETACHED 
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Comments 
The tape is scanned to verify 
that all of the files are on it. 


Tape mark indication. 


Two tape marks indicate the end 


of the tape. 


The CP DETACH command rewinds 


and detaches the tape. 


to be read. 


Message indicating the tape is 


attached. 


One file is to be read onto disk. 
The TAPE command displays the 
Name of the file loaded. Any 
existing file with the same 
filename and filetype is erased. 
The remainder of the first tape 


file is scanned. 


The second tape file is scanned. 


The tape is backed up and 


positioned in front of the 
last tape file. 


The tape is forward spaced past 


the tape mark. 


The next two tape files are 


going to be read. 


The tape is detached. 


Readers, and Tapes 


Indication of end of first tape file. 
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Tape Labels in CMS 


Support in the CMS component of VM/SP to process labelled tapes includes 
the following features: 


e Checks IBM standard labels on input 
e Writes IBM standard labels on output 


e Allows you to specify routines to process standard user labels during 
DOS and OS macro simulation under CMS 


e Allows you to specify exits for processing tapes with nonstandard 
labels during execution of CMS macro simulations and some CMS tape 
operation commands CMS processes all tape labels; CP does not process 
tape labels. 


Limitations 


CMS tape label processing does not include: 

e Label processing for tapes that are read backwards 
e Processing of multivolume files on tapes 

e Support for ANSI tapes or ASCII lakels 


e Label processing for any functions of the CMS TAPE command except the 
two functions DVOL1 and WVOL1 that process VOL1 labels 


USER RESPONSIBILITIES 


You must initiate all your own tape label processing. To specify that 
you have a labelled tape, use the FILEDEF command for an OS simulation 
program, or use a DOS DTFMT macro for a CMS/DOS program. You can also 
use the TAPESL macro to process standard HDR1 and EOF1 labels and the 
CMS TAPE command to write and display standard VOL1 labels. You can 
provide IBM standard label description details with the LABELDEF command 
for all types of label processing. After label processing has’. been 
requested, it occurs automatically and there is ho interaction between 
you and CMS unless an error occurs. See the "Error Processing" section 
later in this publication for a discussion of error processing. 


LABEL PROCESSING IN OS SIMULATION 


If you are running an OS simulation program and using OPEN and CLOSE 
macros, you specify the type of label processing you want in a FILEDEF 
command for a given file. Detailed information about the FILEDEF 
command is found in the VM/SP CMS Command and Macro Reference. You may 
specify that you want standard label processing (with SL) or nonstandard 
label processing (with NSL). If you choose nonstandard label 
processing, you must already have written a routine to process 
nonstandard labels. The name of this routine must be specified by the 
filename in the NSL parameter on FILEDEF. An example of nonstandard 
label processing is given in the section "NSL Processing". To be sure 
that the tape you are using contains no IBM labels, you may specify no 
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label processing (NL) in the FILEDEF command. When NL is specified, CMS 
does not open files ona tape containing a VOL1 label as its first 
record. You also can specify bypass tape label processing (BLP) ona 
FILEDEF command. BLP tells CMS to bypass tape label processing for a 
file, and instead, to position the tape at a particular file before 
processing the data records in the file. If you specify LABOFF for a 
FILEDEF tape file, label processing is turned off and there is no tape 
positioning or label checking. 


LABOFF is the default, so you do not receive any processing or tape 
positioning for a tape file unless you specifically request it. If you 
specify BLP, NL, SL, or SUL processing but omit a positional paraneter, 
the position defaults to 1 and the tafe is positioned at the first file. 
Examples of NL, BLP, and LABOFF processing are given in the sections "No 
Label (NL) Processing". Bypass Label (BLP) Processing", and "Label Off 
(LABOFF) Processing". 


IBM Standard Tape Label Processing 


For IBM standard labels, you specify, SL or SUL, and optional positional 
and VOLID parameters. On a FILEDEF command, SUL means standard user 
labels. Everything you do for SL files, you must also do for SUL files. 
The positional parameter for standard label files works the same way it 
does in OS/VS. If you specify: 


filedef filex tap1 sl 2 


the tape is spaced to what is physically the fourth file on the tape 
before processing begins. The reason for this spacing is that a 
standard labelled tape has one header file, one data file, and one 
trailer file for each data file. If you leave off the positional 
parameter: 


filedef filey tap3 sul 
you get the first file on the tape. 


The optional VOLID parameter on the FILEDEF command allows’ you to 
specify the volume serial number in the VOL1 label of a tape in case you 
want only the VOL1 label checked on the tape. If you want to specify 
other fields in IBM standard labels, you must also provide a LABELDEF 
statement for the tape file. The LABELDEF statement allows you to 
assign values to all fields in a standard HDR1 or EOF1 label. A 
complete description of how the LAPELDEF command works may be found in 
the "LABELDEF Command" section later in this publication. 


The following command defines filez as a standard labelled tape file 
on a tape with a VOL1 label and a volume serial number of DEPT78: 


filedef filez tap1 sl volid dept78 


If you also wish to specify a data set identifier for filez, you must 
furnish a LABELDEF command for filez as well as the FILEDEF command. 
Data set name may not be specified on the FILEDEF command. The LABELDEF 
statement below assigns a data set name of payroll to filez. 


labeldef filez fid payroll 
You can also specify file sequence number, volume sequence number, 
expiration date and other fields on a LABELDEF command. However, if you 


are uSing OS Simulation macros (OPEN, CLOSE, READ, WRITE, GET, POT, 
etc.) to process your tape file, the only LABELDEF parameter that has 
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meaning for input files is fid (data set identifier). This is the only 
field that is checked on input by OS simulation. The other LABELDEF 
fields are used to specify values to be written in output labels. They 
are also used by other types of tape label processing (CMS/DOS and CMS) 
to check input labels. If no LABFLDEF command has been supplied for 
output files, default values are used to write out labels (see the 
section on the LABELDEF command for the default values). 


After you have set up your descriptive information for a standard 
labelled tape file in FILEDEF and LABELDEF statements, you run a regular 
OS simulation program under CMS. During program execution, HDR1 and 
HDR2 labels are written or checked at OPEN time. EOF1 and EOF2 labels 
are written or checked at CLOSE time. To have EOF labels processed, you 
must issue a CLOSE macro. The VOL1 label on a tape is checked whenever 
a file on that tape is opened if the user has specified a VOLID 
parameter on his FILEDEF statement or LABELDEF statement for the file. 
If the volid is specified on both LABELDEF and FILEDEF, the more recent 
specification is used. If no volid is specified, it is not checked. 
After checking the volid, the tape is positioned and the HDR label is 
processed. For processing multifile volumes, you may wish to’ use the 
LEAVE option on the FILEDEF command. This option prevents a tape fron 
being rewound and positioned before each tape file is processed. The 
LEAVE option does not exist on an OS DD statement. 


For input files, HDR2 and EOF2 labels are skipped. There is no nerge 
of information from a HDR2 label with information in the DCB as there is 
under an OS/VS operating system. Output HDR2/EOF2 records are written 
from information in the DCB and the CMSCB (FCBSECT). Note that the tape 
density and TRITCH fields in HDR2/EOF2 records are taken from what the 
user specifies in his FILEDEF command for the tape file. They may not 
correspond to the actual density and TRTCH fields used to write the 
tape. 


To process standard user labels in OS _ simulation, you must do the 
following: 


1. Specify the file as SUL in a FILEDEF command. 


2. Provide a routine to process the user standard labels in your 
progran. 


3. Put the address of the user label routine in the DCB EXIT list of 
the DCB for the file. See the IBM publication OS/VS1 Data 
Management Services Guide or OS/¥S2 MVS Data Management Services 
Guide, for instructions on how to establish a DCB EXIT list, and 
the exact linkage for communication between user label routines and 
the operating system. This exact linkage should be used under CMS 
with the following exceptions: 


ae There is no support for code x'06' EOV EXIT routine. 


b. For input labels, return codes 8 and 12 from the user routine 
are not supported. If an input return code is not 0, it is 
treated as if it were 4. 


4. Note that your standard user label routines do not perform any 
input/foutput. They set up an output label for writing, but the CMS 
tape label processing routines actually write out the label. For 
input, the CMS label processing routines read in your user standard 
label but then give control to your routine to check the label. 
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No Label (NL) Processing 


You should specify NL in the FILEDEF command when you expect a tape does 
not contain any IBM standard tape labels. CMS reads your tape at the 
time a file is opened and does not open the file if the tape contains a 
VOL1 label as its first record. If the tape does not contain a VOL1 
label, a file is opened and the tare is positioned by using the position 
parameter (n). For example, if you specify: 


filedef fileg tapi n1 2 


fileq is not opened if the tape on tapi (181) has a VOL1 label. If the 
tape does not have a VOL1 label, fileq is opened and the tape is 
positioned at the second file. If you do not specify a_ position 
parameter, the tape is positioned at the first file, (that is, the load 
point). 


Bypass Label (BLP) Processing 


You should specify BLP in the FILEDEF command to bypass tape label 
processing. CMS does not check your tape for an IBM standard tape 
label. It uses the position parameter you specified to position the 
tape during open processing. If you do not specify a position 
parameter, the default is 1. For example: 


filedef fileabc tapel blp 4 


positions the tape at the fourth file when it opens fileabc. Because 
CMS does not know whether files on the tape are label files or data 
files, the tape is positioned at what is physically the fourth file, 
regardless of file content. Any label files on the tape are included in 
counting files. 


t 


abel Off (LABOFF) Processing 


You should specify LABOFF in the FILEDEF command if you want no 
positioning or label processing to occur during open processing. The 
position parameter is not valid for LABOFF. If you specify LABOFF, and 
your tape is positioned at record 6 in the third file before you issue 
an OPEN macro, the tape is positioned at exactly the same record after 
open processing (record 6 in the third file). The following FILEDEF 
command does not move tape2 (182) before processing the data in fileb: 


filedef fileb tap2 laboff 


2 a os 


In order to process nonstandard labels, you must write your own routine 
to read, write, and check the labels. If you have such a routine as a 
CMS TEXT or MODULE file, you put the filename of the routine after the 
NSL keyword parameter in the FILEDEF command for the file. The filename 
must be the name of the first CSECT in the program. It is to this point 
that control is transferred when the NSL routine gets control. If you 
do not have a TEXT or MODULE file with the NSL filename you specify, you 
get an error message. The OPEN and CLOSE routines will load your nodule 
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if it is not already in storage and will pass control to it at the time 
they are opening or closing the file. Your routines will then be 
responsible for processing the tape labels. Nonstandard label routines 
must do the actual reading and writing of tape labels as well as 
checking and setting up the label. This is one of several ways 
nonstandard label processing is different from standard user label 
processing. Because the CMS label processing routines do not know the 
Size or format of your nonstandard labels, they cannot read or write the 
labels. 


If you use a MODULE file for an NSL routine, it is important that you 
create the MODULE file so that it starts at an address that will not 
allow it to overlay the program or command you are executing at the time 
the NSL routine is invoked. The reason for this restriction is that the 
NSL routine is dynamically loaded while your program is executing. For 
the TAPEMAC and TAPPDS commands, starting the NSL routine at an address 
above X'21000" prevents such an overlay. If the NSL routine is invoked 
from your own program which is running in the user area, you nust 
determine how big your program is and where the NSL MODULE file should 
be located to prevent overlay. Note that you do not have to specify a 
Starting address for NSL routines that are TEXT files. The CMS loader 
loads such files for you at an address that does not cause an overlay. 


Although any user may write his own NSL routine, it is expected that 
a system programmer will usually write such routines and then other 
programmers in the installation will use them. Before writing an NSL 
routine, read the Introduction to CMS, Interrupt Handling, and CMS 
Functional Information sections in Part 3 of the VM/SP systen 
Programmers Guide. In order to ensure proper communication with the CMS 
system routines, you must use the linkage described below when you write 
nonstandard label routines. 


When an NSL tape label processing routine gets control, register 1 
points to a 16-byte parameter list with the following format: 


byte O | Type | Caller | Tape Mode— | ReServed | 
{ call | id | Set Byte | | 
| ; 
byte 4& | TAPID | 
| —————— | — ID parameter 
byte 8 | FCBSECT address | | for 
| { | TAPEMAC and 
byte 12 | DCB address [ | TAPPDS 
ee eee eee Sd 


The Type call field is a code telling the type of label processing 
being done: 


x*'OO!* is OPEN input 

x'Out is OPEN output 

x'O8! is CLOSE input 

x'oc? is CLOSE output 

x10 is End of Tape output 


The Caller id is a one-byte code which is one of the following: 


x'80! Call by OS sinulation 
x'20°% Call by CMS TAPEMAC or TAPPDS commands 


Tape modeset byte is used to communicate with the CMS tape I/0 
routines. It is a one byte hexadecimal code that depends on the type of 
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tape (7 or 9 track), tape density, etc. For further information on the 
Mode Set, see the TAPE command description in the VM/SP CMS Command and 
Macro Reference. (You probably will pass this byte to the CMS tape 
controlling module to read and write your tape labels and will never 
need to know what its codes mean.) 


FCBSECT address is the address of the CMSCB (FCBSECT) for the tape 
file you are processing. 


DCB address is the address of the DCB for the tape file you are 
processing. 


Note that for the TAPEMAC and TAPPDS commands, the same interface is 
used, except that instead of the FCBSECT and DCB address fields, the 
eight character identifier specified in the ID=identifier field in the 
command is passed. This identifier enables you to identify which file 
you are processing since the TAPEMAC and TAPPDS commands do not work 
With CMSCBs or DCBs. 


Control is passed to your NSL routine by a BALR 14,15 instruction so 
register 15 contains the address of your routine when you receive 
control. Register 14 contains the address you should return to when you 
are finished processing the nonstandard labels. You can return with a 
BR 14 instruction. When you receive control, register 13 points toa 
save area in which to store the callers register. The save area linkage 
is standard OS/VS linkage. You receive control with a PSW key of X'E! 
which allows you to modify only user storage. When you are finished 
processing, place a code in register 15 to the CMS label processing 
routine that called your routine. Place the value 0 (zero) in register 
15 if there have been no errors and you want processing to continue 
normally and the data set to be opened. If you return a nonzero value 
in register 15, a message is issued to your terminal and the data set is 
not opened. 


If you write the following FILEDEF statement: 
filedef tapf1 tap? nsl readlab 


and have a program called RFADLAB as a MODULE or TEXT file, your progran 
will receive control when the data set called tapf1 is opened. When 
your program gets control, register 1 contains the address of the 
parameter list described above. Using the data in this parameter list, 
you are able to read or write your own tape header labels. When the 
same data set is closed, your program again receives control and you can 
read or write your own trailer labels. Your program can test whether it 
is getting control for OPEN or CLOSE by examining the type call byte in 
the parameter list passed to you. If the type call byte is x'10', your 
NSL routine is being invoked while you are writing an output data set 
and you have reached the reflective mark that indicates end of tape. 
You may wish to do special processing in this case. See the "End of 
Tape" and "End of Volume" section in this publication for further 
information on end of tape processing. 


Differences Between Tape Label Processing Under OS/VS and 


Un ¥S S Simulation 
in CMS 


There are a few minor differences in the way CMS OS simulation processes 
tapes and the way OS/VS processes them. These differences are listed 
below. 


e If you are using OS/VS and you do not specify any label parameter on 
your JCL statement, the default is SL or standard labels. When you 
use OS simulation under CMS and do not specify any label information 
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on a FILEDEF statement, the default is LABOFF. LABOFF turns off 
label processing and nothing is done to position the tape or process 
labels. Thus, if you specify no label information on FILEDEF, the 
system will process your tape files exactly the same way they are 
processed on a CMS system that has no tape label processing 
facilities. 


You must specify CLOSE to process all trailer labels. No automatic 
CLOSE occurs at end of data or after reading a tape mark. There is 
no EOV monitor to process labels before a data set is closed. If an 
input tape is positioned at an EOF1 or EOV1 record when CLOSE is 
issued, the label is processed. If a tape file is closed before all 
data records are read, the trailer label is not processed. Output 
tapes have EOF records written only at CLOSE time. 


There is no deferred label processing under OS simulation in CMS. 


When the user has not specified a block count routine in his DCB EXIT 
list under OS/VS, the program abends when a block count error occurs. 
Under CMS, this condition produces a message that asks whether or not 
to abend the operation. 


Certain fields in HDR1 and EOF1 labels default to values different 
from those under OS/VS. These values can always be specified ina 
LABELDEF command if the user does not like the default values. For 
example, the default for data set name in an output label under OS 
Simulation is DDNAME and not DSNAME. The default data set sequence 
number is always one even when the data set is not the first data set 
on the tape. The default volume sequence number is always one. Read 
the section on the LABELDEF command in this manual to learn what the 
default values are under CMS. You can find what default values are 
in OS/VS by reading the IBM publication OS/VS Tape Labels. Note that 
you can always get exactly what you want written on a tape label by 
explicitly specifying the field on a LABELDEF command. For example, 
you can specify DSNAME as FID on such a command and have it written 
in the label instead of DDNAME. 


Default volids (when you do not specify a volid ina LABELDEF or 
FILEDEF statement) in output HDR1 and EOF1 records under CMS will be 
CMSO0O1 and will not be the actual volume serial in the VOL1 record 
already on the tape. It is recommended that you always specify the 
volid in FILEDEF or LABELDEF to he sure the information written is 
correct. 


Expiration date specification is always done in absolute form rather 
than by retention period. You must always use the form yyddd where 
yy is the year (0-99) and ddd the day (0-366). CMS does not handle 
expiration dates specified by retention periods. 


When CMS reads a HDR1 label and finds an unexpired file, it always 
issues a message allowing you to enter ‘IGNORE or "ERROR*'. '‘'ERROR® 
prevents opening the file but "IGNORE" lets you ignore the error and 
- write over the unexpired file. 


The NSL routine linkage is quite different under CMS than in OS/VS. 
(See the section "NSL Frocessing" for details.) 


Volume serial number verification occurs every time a file on a tape 
is opened under OS simulation unless the FILEDEF LEAVE option is used 
for multifile tapes. 


Existing VOL1 labels are not automatically rewritten for density 
incompatibility in CMS as they are in OS/VS. 

HDR2 records are skipped for input under CMS for OS simulation. They 
are not checked and information in them is not merged with DCB 
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information. HDR2 records are written (with information obtained 
from the DCB) on output. 


e Blank tapes used for output in CMS cause the tape to run off the reel 
if you define the tape file as SL or NL. The tape label processing 
routines try to read an existing VOL1 or HDR1 label before writing on 
the tape. Therefore, you should always use the CMS TAPE command to 
write at least one tape mark (for NL tapes) or a VOL1 label (for SL 
or SUL tapes) before using the tape to write an output data set. 


e If you specify a position parameter that is too big (that is, there 
are not that many files on the tape), the tape will run off the reel 
in CMS. 


e There are no user exits for user standard labels for EOV label 
processing in CMS. 


e CMS does not support user return codes of 8 and 12 for input standard 
user labels. If the return code from a user routine is not zero 
after input label processing, CMS treats it as if the return code was 
4. (See the IBM publication OS/VS1 Data Management Services Guide or 
OS/VS2 MVS Data Management Services Guide for details). 


e No count is kept of user standard labels read or bypassed in CMS. If 
more than eight such labels exist, the fact is not detected. 


e User label processing routines do not receive control under CMS when 
an abend or a permanent I/O error occurs. 


e If a CMS output tape is not positioned at a HDR1 label or a tape mark 
when label processing begins, error message 422 is issued. Under 
OS/VS such conditions cause an abend. 


e CLOSE with the REREAD option causes a tape to be rewound under CMS 
and then forward spaced one file if the tape has standard labels. 
Under OS/VS, the tape is backspaced four files and forward spaced one 
file. REREAD for unlabelled tapes in CMS always causes a rewind. 


For further information on OS/VS tape label processing, refer to the 
following IBM publications: OS/VS1 Data Management Services Guide, 
OS/VS2 MVS Data Management Services Guide, and OS/VS Tape Labels. 


For details on end-of-tape/end-of-volume processing under CMS, see 
the "End-of-Volume" and "End-of-Tape Processing" section later in this 
publication. 


LABEL PROCESSING IN CMS/DOS 


You specify the type of label processing you want in CMS/DOS on a DTFMT 
macro in exactly the same way you specify it when you want to run your 
program under VSE/AF. See the VMN/SP System Programmer's Guide for 
details on CMS support for the DTFMT macro. 


Labelled tapes are only supported if you use the DTFMT macro. There 
is no support for labelled tapes in CMS/DOS for any other type. If you 
try to read labelled tapes with a DTFCP or DTFDI macro, input standard 
IBM header labels are skipped, but no other input labels are processed. 
Output tapes with standard labels have these labels overwritten with a 
tape mark. All tape work files are treated as output unlabelled files 
in CNS/DOS although they are defined by a DTIFMT. Tapes used for such 
files have a tape mark written as the first record when the file is 
opened. 
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Unlabelled and Nonstandard Labelled Tapes 


You define an unlabelled tape with the DTFMT parameter FILABL=NO. The 
tape file is processed as having no labels. 


You define a nonstandard labelled tape with the DIFMT parameter 
FILABL=NSTD. You also must provide a routine to process your 
nonstandard labels in the LABADDR=parameter of the DTFMT. Tape 
processing in CMS for these files is the same as it is under VSE/AF. 


Standard Labelled Tapes 


You define a standard label tape with the DTFMT parameter FILABL=STD. 
You also must supply a LABELDEF command to specify label description 
information. This command replaces the VSE/AF TLBL card and is required 
for standard label processing under CMS/DOS. The LABELDEF command is 
discussed in detail in the "LABELDEF Command" section later in this 
publication. 


In order to connect the LABELDEF command for a file with the DTIFMT 
for the same file, you must use the same name to label your DTFMT as you 
use for a filename in your LABELDEF command. If you code a DTFMT macro 
in your program as: 


MT1 DIFMT ---FILABL=STD 
you must then supply the following type of LABELDEF command: 


labeldef mt1 fid yourfile fSseg... 


You can put any description parameters you want on your LABELDEF 
command but the filename for it must be mt1 if you coded MT1 as the 
label on the DTFMT. 


After you have set up your DTFMT and LABFLDEF, you execute your 
CMS/DOS program. HDR1 labels are checked or written when an OPEN macro 
is issued. EOF1 labels are checked or written when a CLOSE macro is 
issued. A VOL1 label volume serial number is checked only if the tape 
is positioned at load point when the label processing begins and if you 
have specified a VOLID parameter on a LABELDEF statement for the file. 
Note, if NOREWIND is not specified in the DIFMT macro for the file, the 
tape is rewound so it is positioned at load point for label processing. 


If you want to process user standard labels as well as’_ standard 
labels in CMS/DOS, you specify FILAPL=STD and also supply a LABADDR 
parameter in the DTFMT for the file. Control is then transferred to 
your label processing routines after standard labels are processed. The 
linkage to user standard label routines is exactly the same as in 
VSE/SAF. 


There are minor differences in the way tapes are processed by CMS/DOS 
and the way they are processed by VSE/AF. These differences are: 


e The tape error messages are CMS error messages and not VSE/AF error 
messages. In some cases VSE/AF allows the system operator to reply 
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NEWTAP to an error message. The system then waits for the operator 
to mount anew tape and continues processing with this new tape. 
Such a reply is never possible under CMS/DOS. In CMNS/DOS, you 
usually can reply IGNORE to ignore a tape label error condition or 
CANCEL to cancel a job. NEWTAP is never allowed. Ina few cases, 
CMS/DOS allows an IGNORE reply where VSE/AF does not. 


You must specify CLOSE to process all trailer labels. No automatic 
CLOSE occurs at end of data or after reading a_ tape mark. If an 
input tape is positioned at an EOF1 or EOV1 record when CLOSE is 
issued, the label is processed. If a tape file is closed before all 
data records are read, the trailer label is not processed. Output 
tapes have EOF records written only at CLOSE time. For nonstandard 
labelled tapes, your own routines do not receive control on input 
when a tape mark is read. You pust issue a CLOSE macro in your 
EOFADDR routine in order to have the trailer labels processed. 


Certain fields in HDR1 and EOF1 labels default to values different 
from those in VSE/AF. For example, the default volume serial number 
written in a HDR1 label is CMSO01 and not the actual volume serial 
number (volid) in the VOL1 label already on the tape. The default 
file sequence and volume sequence numbers are always one even when 
the file is not the first file on the tape. You should read the 
section on the LABELDEF command in this publication to learn what the 
default values are in CMS/DOS. You also can read the IBM publication 
VSE/AF Tape Labels to find what the default values are for VSE/AF. 
If you do not like the default values, you can always specify the 
exact values you want in label fields in a LABELDEF command. 


Expiration date specification is always done in absolute form rather 
than by retention period. You must always use the form yyddd where 
yy 1s the year (0-99) and the dddthe day (0-366). CMS does not 
handle expiration dates specified by retention periods. 


VOL1 labels written in the wrong density are not rewritten 
automatically by CMS/DOS as they are by VSE/AF. 


Blank tapes should not be used for tape files specified as FILABL=STD 
in CMS/DOS; they will run off the reel. Use the CMS TAPE command to 
write a VOL1 label or a tape mark on a blank tape before using it for 
a STD file. 


Not all tape movement and label checking that occurs in VSE/AF occurs 
under CMS. For example, when opening an output file, a VSE/AF systen 
expects the tape to be positioned at a HDR1 label or a tape mark. It 
then backspaces the tape to read the last EOF1 label on the tape. If 
it does not find the label it expects, it issues an error message. 
This check is not performed by CMS/DOS. If the tape is not 
positioned at a HDR1 label or a tape mark when output open processing 
begins, error message 422 is issued. 


After an EOV1 label is written (see "End-of-Tape/End-of-Volune 
Processing" later in this publication), the tape is always rewound 
and unloaded under CMS/DOS. VSE/AF lets a DTFMT parameter control 
whether or not the tape is rewound. 


User label processing routines do not receive control when an I/0 
error occurs under CMS/DOS. 


Control is not passed to user standard label routines in CMS/DOS when 
EOT has been sensed on output and an EOV1 label has been written by 
the system routines. 

Work tapes are not checked for an expiration date when they contain 
standard labels under CMS/DOS. If a tape is to be opened as a work 
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tape, CMS/DOS tests to see if it contains a VOL1 label. If it does, 
a dummy HDR1 label and a tape mark are immediately written on the 
tape after the VOL1 label. If the tape does not contain a VOL1 
label, a tape mark is written at the beginning of the tape. VSE/AF 
checks expiration dates on previously labelled tapes used as work 
tapes and gives the operator a chance to reject the tapes if the 
expiration date has not expired. 


For further information on VSE/AF and CMS/DOS tape label processing, 
refer to the IBM publications, VSE/AF Tape Labels and VSE/AF Macro 
User's Guide. 


CMS TAPESL MACRO 


The TAPESL macro is provided for use in CMS programs that do not use OS 
and DOS simulation features. You can use the CMS TAPESL macro to 
process IBM standard HDR1 and EOF1 labels without using DOS or OS OPEN 
and CLOSE macros. You will proktably use TAPESL with the RDTAPE, WRTAPE, 
and TAPECTL macros. 


TAPESL processes only HDR1 and EOF1 labels. It does not perform any 
functions of opening a tape file other than label checking or writing. 
The TAPESL macro generates linkage to the CMS tape label processing 


routine that actually processes the label. The macro generates a block 
of data (32 bytes long) in order to communicate with the tape label 
processing routines. TAPESL 1s used both to check and to write tape 


labels. A LABELDEF command must be issued prior to running the progran 
that contains this macro. The LABID parameter of the TAPESL macro is 
used to specify the name of the LABELDEF to be used. For example, if 
you use the macro: 


TAPESL HOUT, 181,LABID=GOODLAB 


in your assembly language program, you must supply a LABELDEF command 
for GOODLAB: 


labedef goodlab fid filel0O fseg 4 exdte 78235 


The tape must be positioned correctly (at the label to be checked or at 
the place where the label is to be written), before you issue the macro. 
TAPECTL may be used to position the tape. TAPESL reads or writes only 
one tape record unless you specify SPACE=YES for input. Then it spaces 
the tape to beyond the tape mark that ends the label file. MTAPESL reads 
and checks a tape VOL1 label provided the tape is positioned at load 
point and the user has specified a volid in his LABELDEF command. 


TAPE LABEL PROCESSING BY CMS COMMANDS 

There are three types of CMS commands that do some type of tape label 
processing. They are: 

e TAPEMAC and TAPPDS commands 


e TAPE command 
e MOVEFILE command 
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TAPEMAC and TAPPDS have operands where you can indicate the type of 
label processing you want. The tape must be positioned properly (at the 
data file or label file you want) before you issue the command. The 
TAPE command may be used for positioning. A separate LABELDEF command 
is required for these commands if IBM standard label checking is 
desired. If SL label type is specified without a labdefid, standard 
header labels are displayed on the terminal but not checked by the CMS 
label processing routines. The command: 


tapemac macfile SL (tap2 


displays any standard labels that exist on your terminal while the 
series of commands: 


labeldef maclab fid macro volseg 2 crdte 77102 
tapemac macfile sl maclab (tap2 


invokes the CMS tape label processing routines. These routines check to 
see that your tape has a HDR1 label that has a file identifier of macro, 
a volume sequence number 2, and a creation date of 77102. VOL1 labels 
are not checked during label processing by TAPEMAC and TAPPDS unless the 
tape is positioned at load point and you have specified a volid on your 
LABELDEF command. The DVOL1 function of the TAPE command can be used 
for volume verification before positioning the tape if the user does not 
want to start at the first file. These commands process only 4HDR1 
labels; they skip HDR2, UHL, and all trailer labels without processing 
then. 


To process nonstandard tape labels with TAPEMAC and TAPPDS, you use 
the same interface described in the section "NSL Processing under OS 
Simulation." The only difference is that instead of putting the CMSCB 
and DCB addresses in the parameter list, the ID parameter you placed in 
the command line is passed to your NSL routine. 


tappds pdsfile cmsut1 * nsl superck id XY212345 


passes the EBCDIC identifier XYZ12345 to your nonstandard label checking 
routine called SUPERCK. This identifier may be up to eight characters 
long and is left justified in bytes 8-15 of the parameter list. You can 
use the identifier to inform your NSL routine of what file you are 
processing. 


Tape Command DVOL1 and WVOL1 Functions 


Use the DVOL1 function of the CMSTAPE command to display the VOL1 label 
of a tape on your terminal. You may use this command to ensure the 
System operator has nounted the correct tape before you begin processing 
the tape. If the tape does not have a VOL1 label and you issue the 
CMSTAPE command, you are informed that the VOL1 label is missing. Do 
not use TAPE DVOL1 if you have a blank tape. If TAPE DVOL1 is issued 
and a blank tape is used, CMS will search the entire tape to find the 
label record; since the tape is void of any records, the tape will run 
off the end of the reel. 


Use the WVOL1 function on the TAPE command to write a VOL1 label on a 
tape. You can specify a one- to six-character volume serial number 
(volid) through this command and also a one- to eight-character owner 
field. 
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MOVEFILE Command 


You can use the MOVEFILE command to move labelled tape files if these 
files are defined as labelled by the FILEDEF command. The MOVEFILE 
command supports only SL, NSL, BLP, NL, and LABOFF processing. sUL 
files are processed as SL files and no user exitsS are taken. 


You can also use the MOVEFILE command to display tape labels on your 
terminal if you want to see what these labels look like. The following 
sequence displays the VOL1 and first HDR1 labels on tap4 if the tape has 
Standard labels: 


filedef in tap4 
filedef out term 
tape rew (tap4 


move in out 


LABFLDEF COMMAND 


The LABELDEF command is used to specify the exact data you want written 
in certain fields of a HDR1 or EOF1 tape label for output. It can also 
be used to specify fields in the same labels that you want checked on 
input. If you do not explicitly specify a field for output, a default 
value is used. If you do not explicitly specify a field for input, the 
field is not checked. For example: 


labeldef abc fid master volsegq 1 exdte 77364 


used for input tells CMS to check the file identifier volume sequence 
number and expiration date in an input HDR1 label. No other fields in 
the label are checked. The same specification used for output causes 
the HDR1 label to have MASTER written in the file identifier field, 1 
written in the volume sequence number field and 77364 written in the 
expiration date field. Default values are written in the HDR1 fields 
that are not specified. 


Default values for HDR1 labels are as follows: 
FID - for OS simulation, the DDNAME (Specified on FILEDEF) 


- for CMS/DOS, the DIFMT symbolic name 
- for CMS TAPESL macro, the LABELDEF id (LABID=labeldefid) 


parameter 
VOLID - CMS001 
VOLSEQ - 0001 
FSEQ - 0001 
GENN - blanks 
GENV - blanks 
CRDTE - current date that label is written 
EXDTE - current date that label is written 
SEC - O 
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The filename on the LABELDEF command is used to connect your label 
definition to a file defined elsewhere. This is why you specify 
different data for file name depending on the type of tape label 
processing you are doing. Filename is DDNAME for OS simulation, DIFMT 
symbolic name for CMS/DOS and labeldefid for TAPESL. 


The LABELDEF command takes the place of the VSE/AF TLBL statement for 
CMS/DOS. 


END-OF-VOLUME AND END-OF-TAPE PROCESSING 


There is no true end-of-volume support available with CMS tape label 
processing. FEOV instructions are not supported under OS simulation and 
there is no automatic volume switching. Multivolume files are not 
supported. The following features exist to aid the IBM standard label 
tape user when he reaches end-of-tape on output or an EOV label in 
input. These are the only ways in which CMS supports EOV processing. 


e Input - When a CLOSE macro is issued or when a TAPESL macro processes 
an input trailer label, a message is issued if the label read is an 
EOV1 label instead of an EOF1 label. The EOV1 label is’ then 
processed exactly as if it were an EOF1 label. You must request that 
the operator mount anew tape and reopen a file if you want to 
continue procesSing the data. 


e Output - Under CMS/DOS and OS’ simulation processing only (that is, 
the processing does not occur for TAPESL or CMS commands), the 
following limited EOV procesSSing occurs: 


a. If you specify that you have an IBM standard label tape file, a 
Single tape mark is written to end your data. This occurs when 
end-of-tape is sensed on output while you are using regular access 
method macros to write the file. The tape mark is written 
immediately after the record that caused the EOT to be sensed. 
Following this tape mark, CMS writes an EOV1 label and a single 
tape mark. It then rewinds and unloads your tape. A message is 
issued telling you that an EOV1 label was written. If you 
specified nonstandard labels instead of writing the EOV1 label, an 
exit to the nonstandard label routine you specified for the file 
is taken after the end-of-data tape mark is written. For BLP or 
NL files, only the ending tape mark is written. 


b. CMS/DOS jobs are always canceled after an EOT condition is 
detected on output. In order to continue processing the tape, you 
must have a new tape mounted, run the same job over again or run a 
new job and reopen the file. 


c. OS simulation programs that use QSAM or contain a BSAM CHECK macro 
cause an abend when EOT is detected, with code 001 after an error 
message. A BSAM program that does not use a CHECK macro has no 
way of detecting the EOT condition. Such a program continues to 
try to write oon the tape after it is rewound and unloaded. The 
program enterS a wait state rather than continue running to a 
normal or abnormal completion. Therefore, you should always 
include a BSAM CHECK macro after the WRITE if you expect your 
program to reach end-of-tape. OS simulation users are also 
responsible for completing processing on a new tape with the same 
or a new job after an EOT is detected. 


d. If you are a CMS/DOS user you always get the automatic output 


end-of-tape processing described above. However, if you are an OS 
Simulation user and do not want CMS to do any special end-of-tape 
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processing, you can suppress it by using the NOEOV option on your 
FILEDEF command for the file. If you enter: 


filedef dd1 tap3 sl (noeov 


no tape marks or EOV1 labels are written when EOT is’ sensed on 
output. Your tape is not rewound and unloaded. However, the 
program causes an abend if you use QSAM or include a BSAM CHECK 
macro after your WRITE macro. Without a CHECK macro, a_ BSAM 
program runs the tape off the reel when EOT is sensed and NOEOV is 
specified. 


ERROR PROCESSING 


When the standard label processing routines find errors or discrepancies 
on tape labels, they send a message to the CMS terminal user who is 
processing the tape. After an error message is issued, the user can ask 
the system operator to mount a new tape, use the CMS TAPE command to 
position the tape at a different file, or respecify his’ label 
description information. If you are a terminal user and want another 
tape mounted, you send the system operator a message telling him what 
tape to mount. 


Some errors cause program termination and others do not. The effect 
of tape label processing errors depends on both the type of error and 
the type of program (that is, CMS/DOS, OS simulation, CMS command, etc.) 
that invokes the label processing. The following are general guidelines 
on error handling: 


e Messages identifying the error are always issued. 


e Under OS simulation, tape label errors result in open errors. These 
errors prevent a tape file fron being opened. They do not 
necessarily end a job. Errors in trailer labels (except block count 
errors) have no effect on processing. 


e In CMS/DOS, the terminal user is generally given two choices: ignore 
the error or cancel the job. The new-tape option is not allowed. 


e The CMS commands TAPEMAC and TAPPDS terminates with a non-zero return 
code after a tape label error. 


e Certain error situations such as unexpired files and block count 
errors for OS simulation allow the user to ignore the error and do 
not cause open errors. In these cases, the user enters his decision 
at the terminal after he is notified of the error. 


e Errors that occur during the loading of an NSL routine cause an abend 
(code 155 or 15A). A block count abend gives an error code of 500. 


In all cases, after an error has been detected and diagnosed, you 
must decide what to do. You may wish to have a new tape mounted and 
then re-execute the command or you may want to respecify your LABELDEF 
description if it was incorrect. You can also use the TAPE command to 
space the tape to a new file if it was positioned incorrectly. 
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THE MOVEFILE COMMAND 


The MOVEFILE command can copy sequential tape files into disk files, or 
seguential disk files onto tape. It can be particularly useful when you 
need to copy a file from a tape and you do not know the format of the 
tape. 


To use the MOVEFILE command, you must first define the input and 
output files using the FILEDEF command. For example, to copy a file fron 
a tape attached to your virtual machine at virtual address 181 to a CMS 
disk, you would enter: 


filedef input tap1 
filedef output disk tape file a 
movefile input output 


This sequence of commands creates a file named TAPE FILE Ail. Then use 
CMS commands to manipulate and examine the contents of the file. 


MOVEFILE can also be used to display tape labels and/or move labelled 
tape files. See "Tape Labels in CMS" for details. 


TAPES CREATED BY OS UTILITY PROGRAMS 


The CMS command TAPPDS can read OS partitioned and sequential data sets 
from tapes created by the IEBPTPCH, IEBUPDTE, and IEHMOVE utility 
programs. When you use the TAPPDS command, the OS data set is copied 
into a CMS disk file, or in the case of partitioned data sets, into 
multiple disk files. 


IEBPTPCH: Sequential or partitioned data sets created by JEBPTPCH must 
be unblocked for CMS to read them. If you have a_ tape created by this 
utility, each member (if the data set is partitioned) is preceded with a 
card that contains "MEMBER=membername". If you read this tape with the 
command: 


tappds * 


then, CMS creates a disk file from each member, using the membername for 
the filename and assigning a filetype of CMSUT1. If you want to assign a 
particular filetype, for example TEST, you could enter the command as 
follows: 


tappds * test 


If the file you are reading is a sequential data set, you should use the 
NOPDS option of the TAPPDS command: 


tappds test file (nopds 


The above command reads a sequential data set and assigns it a file 
identifier of TEST FILE. If you do not specify a filename or filetype, 
the default file identifier is TAPPDS CMS0UT1. 


IEBUPDTE: Tapes in control file format created by the IEBUPDTE utility 
program can be read by CMS. Data sets may be blocked or unblocked, and 
way be either sequential or partitioned. Since files created by 
IEBUPDTE contain ./ADD control cards to signal the addition of members 
to partitioned data sets, you must use the COL1 option of the TAPPDS 
command. Also, you must indicate to CMS that the tape was’ created by 
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IEBUPDTE. For example, to read a partitioned data set, you would enter 
the command: 


tappds * test (update coll 
The CMS disk files created are always in unblocked, 80-character format. 


IEHMOVE: OS unloaded partitioned data sets on tapes created by the 
IEHMOVE utility program can he read either by the TAPPDS command or by 
the TAPEMAC command. The TAPPDS command creates an individual CMS file 
from each member of the PDS. 


If the PDS is a macro library, you can use the TAPEMAC command to 
copy it into a CMS MACLIB. A MACLIB, a CMS macro library, has a special 
format and can usually be created only by using the CMS MACLIB command. 
If you use the TAPPDS command, you have to use the MACLIB command to 
create the macro library from individual files containing macro 
definitions. 


SPECIFYING SPECIAL TAPE HANDLING OPTIONS 


For most of the tape handling that you do in CMS, you do not have to be 
concerned with the density or recording format of the magnetic tapes 
that you use. There are, however, some instances when it may be 
important and there are command options that you can use with the TAPE 
command MODESET operand and with ASSGN and FILEDEF command options. 


The specific situations and the command options you should use are 
listed below. 


e If you are reading or writing a 7-track tape and the density of the 
tape is either 200 or 556 bpi, you must specify DEN 200 or DEN 556. 


e If you are reading or writing a 7-track tape with a density of 800 
bpi, you must specify 7TRACK. 


e If you are reading or writing a 7-track tape without using the data 
convert feature, you must use the TRICH option. 


e If you are writing a tape using a 9-track dual density tape drive 
with the 9TRACK option specified, and you want the density to be 800 
(on an 800/1600 drive) or 6250 (on a 1600/6250 drive), then you must 
specify DEN 800 or DEN 6250. 


e If you are writing a tape, the default tape block size is 4096 bytes 
plus a 5-byte header. This format is not compatible with previous 
VM/370 systems. Therefore, if you want to write a tape compatible 
With previous VM/370 systems, you must use the ‘'BLKSIZE 800' option 
of the TAPE command. The TAPE command is described in detail in 
VN/SP CMS Command and Macro Reference. 


Using Remote Spooling Communications 


You can send printer, punch, or reader spool files to users at remote 
locations. To send a spool file, you must know the userid of the 
virtual machine at your location that is running RSCS and the location 
identification (locid) of the remote location. If you are sending a 
spool file to a particular user at the remote location, you should also 
know that userid of the user. 
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The CP commands that you can use to transmit files across the network 
are TAG and SPOOL. The TAG command allows you to specify the locid and 
userid that are to receive a spool file, or, in the case of tagging a 
printer or punch, of any spool files produced by that device. With the 
SPOOL command, you spool your virtual device to the RSCS virtual 
Machine. You can also use the TRANSFER command to transfer files fron 
your own virtual card reader. 


Note: The VM/SP component Remote Spooling Communications Subsysten 
(RSCS) is technically at a Release 6 level of the product. It does not 
contain anew function supportive of the new CP and CMS function. 
However, the Remote Spooling Communications Subsystem (RSCS) Networking, 
Program Number 5748-XP1 is available and has been technically advanced 
to function supportively with VM/SP. 
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Part 2. Program Development Using CMS 


You can use CMS to write, develop, update, and test: 


e OS programs to execute either in the CMS environment (using OS 
Simulation) or in an OS virtual machine 


e DOS programs to execute in either the CMS/DOS environment or in a DOS 
virtual machine 


e CMS programs to execute in the CMS environment 


The OS and DOS simulation capabilities of CMS allow you to develop OS 
and DOS programs interactively in a time-sharing environment. When your 
programs are thoroughly tested, you can execute them in an OS _ or DOS 
virtual machine under the control of VM/SP. 


"Section 8. Developing OS Programs Under CMS" is for programmers who 
use OS. It describes procedures and techniques for using CMS commands 
that simulate OS functions. 


"Section 9. Developing DOS Programs Under CMS" is for programmers who 
use DOS. It describes procedures and technigues for using CMS/DOS 
commands to simulate VSE/AF functions. 


If you use VSAM and access method services in either a DOS or an OS 
environment, "Section 10. Using Access Method Services and VSAM in CMS 
and CMS/DOS" provides usage information for you. It describes how to 
use CMS to manipulate VSAM disks and data sets. 


You can use the interactive facilities of CP and CMS to test and 
debug programs directly at your terminal. "Section 11. How VM/SP Can 
Help You Debug Your Programs" shows examples of commands and debugging 
techniques. 


The CMS batch facility is a CMS feature that allows you to send jobs 
to another machine for execution. How to prepare and send job streams 
to a CMS batch virtual machine is described in "Section 12. Using the 
CMS Batch Facility." 


As you learn to use CMS, you may want to write programs for CMS 
applications. "Section 13. Programming for the CMS Environment" 
contains information for assembler language programmers: linkage 
conventions, programming notes, and macro instructions you can use in 
CMS programs. 
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Section 8. Developing OS Programs Under CMS 


CMS simulates many of the functions of the Operating System (OS), 
allowing you to compile, execute and debug OS programs interactively. 
For the most part, you do not need to be concerned with the CMS OS 
Simulation routines; they are built into the CMS system. Before you can 
compile and execute OS programs in CMS, however, you must be acquainted 
with the following: 


- OS macros that CMS can Simulate 

- Using OS data sets in CMS 

- How to use the FILEDEF command 

- Creating CMS files from OS data sets 
- Using CMS and OS macro libraries 

- Assembling program in CMS 

- Executing programs 


These topics are discussed below. Additional information for OS VSAM 
users is in "Section 10. Using Access Method Services and VSAM Under 
CMS and CMS/DOS". 


For a practice terminal session using the commands and techniques 
presented in Section 8, see "Appendix D" Sample Terminal Sessions". 


A Note About Terminology 

The CMS system uses many OS terms, but there are a number of OS 
functions that CMS performs somewhat differently. Refer to Figure 14. 
to help you become familiar with some of the equivalents (where they do 
exist) for OS terms and functions. It lists some commonly-used OS terms 
and discusses how CMS handles the functions they imply. 
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OS Tern/Function 


Cataloged procedure 


Data set 


Data Definition (DD) 
card 


Data Set Control 
Block (DSCB) 


EXEC card 


Job Control Language 
(JCL) 


Link—editing 


Load module 


Object module 


Partitioned data 
set 


SETPCAT, JOBCAT 


STEPLIB, JOBLIB 


Utility program 


Volume Table of 
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CMS Equivalent 


EXEC files can execute command sequences 
Similar to cataloged procedures, and provide 
for conditional execution based on return 
codes from previous steps. 


Data sets are called files in CMS. CMS can sin-| 
ulate certain OS data sets and can read real OS| 


data sets only if they are sequential or par— 
titioned. CMS can never write to real OS data 
sets. CMS reads and writes VSAM data sets. 


The FILEDEF command allows you to perform the 
functions of the DD statement to specify 
device types and output fiie dispositions. 


Information about a CMS disk file is contained 
in a file status table (FST). 


To execute a program in CMS you specify only 
the name of the program if it is an EXEC, 
MODULE file, or CMS command. To execute TEXT 
files, use the LOAD and START commands. 


CMS and user—written commands perform the 
functions of JCL. 


The CMS LKED command creates LOADLIB libraries 
from CMS TEXT files and/or OS object nodules. 
The CMS LOAD command loads TEXT files into 
virtual storage, and resolves external 
references; the GENMOD command creates 
absolute nonrelocatable modules. 


Load modules are members of CMS LOADLIB 
libraries. LOADLIB members are loaded, relo— 
cated, and executed by the OSRUN and NUCXLOAD 
commands. Also, LOADLIB members are referenced 
by the LINK, LOAD, ATTACH and XCTL macros. 


Language compiler output is placed in CMS 
files with a filetype of TEXT. 


CMS MACLIBs, TXTLIBs, and LOADLIBs are the only 


CMS files that resemble partitioned data sets. 


VSAM catalogs can be assigned for jobs or job 
steps in CMS by using the special ddnames 
IJSYSCT and IJSYSUC when identifying catalogs. 


The GLOBAL command establishes macro, text, 
and LOADLIB libraries; you can indirectly 
provide job libraries by accessing and 
releasing CMS disks that contain the files and 
programs you need. 


Functions similar to those performed by the OS 
utility programs are provided by CMS commands. 


The list of files on a CMS disk is contained 
in a file directory for 800—byte format CMS 
disks, or in the file directory for CMS disks 


with a 1024-, 2048-, or 4096—byte block format. 
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Figure 14. OS Terms and CMS Equivalents 
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Using OS Data Sets in CMS 


You can have OS disks defined in your virtual machine configuratiof; 
they may be either entire disks or minidisks: their size and extent 
depends on their VM/SP directory entries. You can use partitioned and 
sequential data sets on OS disks in CMS. If you want, you can create 
CMS files from your OS data sets. If you have data sets on OS disks, 
you can read them from programs you execute in CMS, but you’ cannot 
update them. The CMS commands that recognize OS data sets on OS disks 


are listed in Figure 15. 


Command Operation 
ACCESS Makes the OS disk containing the data set available 
to your CMS virtual machine. 


ASSEMBLE| Assembles an OS source program under CMS. 


DDP Copies an entire OS disk to tape. 


DLBL Defines OS data sets for use with access method services 
and VSAM files for program input/output. 

FILEDEF Defines the OS data set for use under CMS by associating 
an OS ddname with an OS data set name. Once defined, 

the data set can be used by an OS program running under 
CMS and can be manipulated by the other commands that 
support OS functions. 


Makes macro libraries or LOADLIB libraries 

available to CMS. You can prepare an OS library 

for reference by the GLOBAL command by issuing a FILEDEF 
command for the data set and giving the data set the 
appropriate filetype of MACLIB or LOADLIB. 


GLOBAL 


LKED Creates CMS LOADLIB libraries from CMS TEXT files and 


or OS object modules. 


OS disks. 
MOVEFILE| Moves data records from one device to another device. Each 
device is specified by a ddname, which must have been 
defined via FILEDEF. You can use the MOVEFILE command to 
create CMS files from OS data sets. 
NUCXLOAD Loads, relocates, and establishes as a nucleus extension 
a load module either from a CMS LOADLIB , an OS module 
library or an OS formatted disk. 
OSRUN Loads, relocates, and executes a load nodule either fron 
a CMS LOADLIB or from an OS module library on an OS 
formatted disk. 
QUERY Lists (1) the files that have been defined with the 
FILEDEF and DLBL commands (QUERY FILEDEF, QUERY DLBL), or 
(2) the status of OS disks attached to your virtual 
machine (QUERY DISK, QUERY SEARCH). 
RELEASE Releases an OS disk you have accessed (via ACCESS) from 
your CMS virtual machine. ; 
STATE Verifies the existence of an OS data set on a disk. 
Before STATE can verify the existence of the data set, 


you must have defined it (via FILEDEF). 
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Figure 15. CMS Commands That Recognize OS Data Sets and OS Disks 
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ACCESS METHODS SUPPORTED BY CMS 


O# access methods are supported, to varying extents, by CMS. Under CMS, 
you can execute programs that use the OS data management macros that are 
supplied for the access methods listed below. 


| { CMS Support for OS | CMS Support for Real | 
| | Sinulated Data Sets | OS Data Sets on OS | 
| Access Method | on CMS Disks | Disks { 
[ \ 
| BDAM | Yes | No j 
; BPAM [ Yes ; Yes (read only) { 
| BSAM | Yes | Yes (read only) | 
| QSAM | Yes | Yes (read only) | 
| VSAM | No | Yes | 


BPAM, BSAM, and QSAM: You can execute programs in CMS that read records 
from OS data sets using the BPAM, BSAM, or QSAM access methods. You 
cannot, however, write or update OS data sets that reside on OS disks. 


BDAM: CMS can neither read nor write OS data sets on OS disks using the 
BDAM access method. 


VSAM Files: CMS can read and write VSAM files on OS_ disks. For 
information on using VSAM under CMS, see "Section 10. Using Access 
Method Services and VSAM Under CMS and CMS/DOS." 


OS Simulated Data Sets 


If you want to test programs in CMS that create or modify OS data sets, 
you can write "OS simulated data sets." These are CMS files that are 
Maintained on CMS disks, but in OS format rather than in CMS format. 
Since they are CMS files, you can edit, rename, copy, or manipulate then 
just as you would any other CMS file. Since they are in OS-simulated 
format, files with variable-blocked records may contain block and record 
descriptor words so that the access methods can manipulate then 
properly. 


The files that you create from OS programs do not necessarily have to 
be OS simulated data sets. You can create CMS files. The format of an 
output file depends on how you specify the filemode number when you 
issue the FILEDEF command to identify the file to CMS. If you specify 
the filemode number as 4, CMS creates a file that is in OS simulated 
data set format on a CMS disk. If you want to read an OS sinulated 
dataset that is variable blocked or fixed blocked, rename the dataset 
with a filemode number of 4. CMS OS Simulation routines are then able 
to read short blocks that are not filled with records. 


CMS can read and write OS simulated data sets using the BDAM, BPAM, 
BSAM, and QSAM access methods. 


When an input or output error occurs, do not depend on OS_- sense 
bytes. An error code is supplied by CMS in the ECB in place of the 
sense bytes. These error codes differ for various types of devices and 
their meaning can be found in the IBM VM/SP System Messages and Codes. 
under DMSxxx120S. 
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Restrictions for Reading OS Data Set 


= Te eee 


The following restrictions apply when you read OS data sets from OS 


disks under CMS: 


e Read-password-protected data sets are not read. 
e RACF password protection is ignored. 


e BDAM and ISAM data sets are not read. 


e Multivolume data sets are read as single-volume data sets. 
End-of-volume is treated as end-of-file and there is no end-of-volune 


Switching. 


e Keys in data sets with keys are ignored; only the data is read. 


e User labels in user-labeled data sets are bypassed. See "Tape Labels 
in CMS" for details. ,sk;.of 3 e Results may be unpredictable if two 


DCBs access the same data set at the same tine. 


e An Indexed VTOC on an OS disk is read the same as a standard OS VTOC 


Since there is no special support in CMS for this. 


Using the FILEDEF Command 


Whenever you execute an OS program under CMS that has input and/or 
output files, or you need to read an OS data set onto a CMS disk, you 


must first identify the files to CMS with the FILEDEF command. 


The 


FILEDEF command in CMS performs the same functions as_ the data 
definition (DD) card in OS job control language (JCL): it describes the 


input and output files. 
When you enter the FILEDEF command, you specify: 
e The ddname 
e The device type 
e A file identification, if the device type is DISK 


e Type of label on your tape file, if tape label processing 
specified 


e Options (if necessary) 


Some guidelines for entering these specifications follow. 


SPECIFYING THE DDNAME 


is 


If the FILEDEF command is issued for a program input or output file, 
then the ddname must be the same as the ddname or file name specified 
for the file in the source progran. For example, you have an assembler 


language source program that contains the line: 


INFILE DCB DDNAME=INPUTDD, MACRF=GL, DSORG=PS, RECFM=F, LRECL=80 


For a particular executicn of this program, you want to use as your 


Section 8. Developing OS Programs under CMS 


151 


input file a CMS file on your A-disk that is named MYINPUT FILE, then, 
you must isSue a FILEDEF for this file before executing the progran: 


filedef inputdd disk myinput file al 
If the input file you want to use is on an OS disk accessed as your 
C-disk, and it has a data set name of PAYROLL. RECORDS.AUGUST, then your 
FILEDEF command might be: 


filedef inputdd c1 dsn payroll.records.august 


SPECIFYING THE DEVICE TYPE 


For input files, the device type you enter on the FILEDEF command 
indicates the device from which you want records read. It can be DISK, 
TERMINAL, READER (for input from real cards or virtual cards), or TAPn 
(for tape). Using the above example, if your input file is to be read 
from your virtual card reader, the FILEDEF command might be as follows: 


filedef inputdd reader 


Or, if you were reading from a tape attached to your virtual machine at 
virtual address 181 (TAP1): 


filedef inputdd tap1 


For output files, the device you specify can be DISK, PRINTER, PUNCH, 
TAPn (tape), or TERMINAL. 


If you do not want any real I/O performed during the execution of a 


program for a disk input or output file, you can specify the device type 
as DUMMY: 


filedef inputdd dummy 


ENTERING FILE IDENTIFICATIONS 


If you are using a CMS disk file for your input or output, you specify: 
filedef ddname disk filename filetype filemode 


Note that if * is used for the filemode of an output file, unpredictable 
results may occur. 


The filemode field is optional; if you do not specify it, your A-disk is 
assumed. If you want an output file to be constructed in OS simulated 
data set format, you must specify the filemode number as 4. For 
example, a program contains a DCB for an output file with a ddname of 
OUTPUTDD, and you are using it to create a CMS file named DAILY OUTPUT 
on your B-disk: 


filedef outputdd disk daily output b4 


If your input file is an OS data set on an OS disk, you can identify it 
in several ways: 


e If the data set name has only two qualifiers, for example 
HEALTH.RECORDS, you can specify: 


152 IBM VM/SP CMS User's Guide 


filedef inputdd disk health records b1 


e If it has more than two gualifiers, you can use the DSN keyword and 
enter: 


filedef inputdd b1 dsn health records august 1974 
filedef inputdd b1 dsn health.records.august.1974 


Or you can request a prompt for a complete data set nane: 


filedef inputdd bi dsn ? 
ENTER DATA SET NAME: 
health. records.august.1974 


Note: When you enter a data set name using the DSN keyword, either 
with or without a request for prompting, you should omit the device 
type specification of DISK, unless you want to assign a CMS file 
identifier, as in the example below. 


e You can also relate an OS data set name to a CMS file identifier: 


filedef inputdd disk ossim file c1 dsn monthly records 
filedef inputdd disk ossim file c1 dsn monthly.records 


Then you can refer to the OS data set MONTHLY.RECORDS by using the 
CMS file identifier, OSSIM FILE: 


state ossinm file c 


When you do not issue a FILEDEF command for a program input or output 
file, or if you enter only the ddname and device type on the FILEDEF 
command, such as: 


filedef oscar disk 
then CMS issues a default file definition, as follows: 
FILEDEF ddname DISK FILE ddname Al 


where ddname is the ddname you assigned in the DDNAME operand of the DCB 
macro in your program or on the FILEDEF command. For example, if you 
assign a ddname of OSCAR to an output file and do not issue a FILEDEF 
command before you execute the program, then the CMS file FILE OSCAR A1 
is created when you execute the program. If the filetype of a CMS input 
file, FILE ddname Al, is the same as the assigned DDNAME, the file can 
be identified by a default file definition. Even though an input file 
can be defined explicitly or by default, if an attempt is made to read 
the file and the file is not found, unpredictable results may occur. 


SPECIFYING CMS TAPE LABEL PROCESSING 


You can use the label operands on the FILEDEF command to indicate that 
CMS tape label processing is not desired (this is the default). If CMS 
tape label processing is desired you can use the label operands on the 
FILEDEF command to indicate the types of labels on your tape. See "Tape 
Labels in CMS" for a description of CMS tape label processing. 
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SPECIFYING OPTIONS 


The FILEDEF command has many options; those mentioned below are a 
sampling only. For complete descriptions of all the options of the 


BLOCK, LRECL, RECFM, DSORG: If you are using the FILEDEF command to 
relate a data control block (DCB) in a program to an input ofr output 
file, you may need to supply some of the file format information, such 
as the record length and block size, on the FILEDEF command line. For 
example, if you have coded a DCB macro for an output file as follows: 


OUTFILE DCB DDNAME=OUT, MACRF=PM, DSORG=PS 


then, when you are issuing a FILEDEF for this ddname, you must specify 
the format of the file. To create an output file on disk, blocked in OS 
Simulated data set format, you could issue: 


filedef out disk myoutput file a4 (recfm fb lrecl 80 block 1600 
To punch the output file onto cards, you would issue: 
filedef out punch (lrecl 80 recfm f 


You must supply file format information on the FILEDEF command line 
whenever it is not supplied on the DCB macro, except for existing disk 
files. 


PERM: Usually, when you execute one of the language processors, all 
existing file definitions are cleared. If the development of a progran 
requires you to recompile and re-execute it frequently, you night want 
to use the PERM option when you issue file definitions for your input 
and output files. For example: 


cp spool punch to * 
filedef indd disk test file a1 (lrecl 80 perm 
filedef outdd punch (lrecl 80 pern 
In this example, since you spooled your virtual punch to your own 


virtual card reader, output files are placed in your virtual reader. You 
can either read or delete then. 


All file definitions issued with the PERM option stay in effect until 
you log off, specifically clear those definitions, or redefine then: 


filedef indd clear 
filedef outdd tap1 (lrecl 80 


In the above example, the definition for INDD is cleared; OUTDD is 
redefined as a tape file. 


When you issue the command: 
filedef * clear 


all file definitions are cleared, except those you enter with the PERM 
option. 


When a program abends, or when you issue the HX Immediate command, 


all file definitions are cleared, including those entered with the PERM 
option. 
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ISP MOD: When you issue a FILEDEF command for an output file and assign 
it a CMS file identifier that is identical to that of an existing CMS 
file, then when anything is written to that ddname the existing file is 
replaced by the new output file. If you want, instead, to have new 
records added to the bottom of the existing file, you can use the DISP 
MOD option: 


filedef outdd disk new update al (disp nod 


The file must be ona disk accessed as’ read/write. Note that an 
extension of a disk is read/fonly. When adding new records using the 
DISP MOD option, erase the end-of-file (EOF) mark at the end of the 
existing file for fixed-block (FB) OS simulated files (filemode of A4). 


MEMBER: If the file you want to read is a member of an OS partitioned 
data set (or a CMS MACLIB or TXTLIB), you can use the MEMBER option to 
specify the membername; for example: 


filedef test c dsn sysi.maclib (member test 
defines the member TEST from the OS macro library SY¥S1.MACLIB. 


AUXPROC: This option allows an auxiliary processing routine to receive 
control during I/O operations. It is valid only when FILEDEF is 
executed by an internal program call and cannot be entered on a terminal 
command. For details on how to use this option of the FILEDEF command, 
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Creating CMS Files From OS Data Sets 


If you have data sets on OS disks, oor on tapes or cards, you can copy 
them into CMS files so that you can edit, modify, or manipulate then 
with CMS commands. The CMS MOVEFILE command copies OS (or CMS) files 
from one device to another. You can move data sets from any valid input 
device to any valid output device. 


Before using the MOVEFILE command, you must define the input and 
output data sets or files and assign them ddnames using the FILEDEF 
command. If you use the ddnames INMOVE and OUTMOVE, then you do not 
need to specify the ddnames when you issue the MOVEFILE command. For 
example, the following sequence of commands copies a CMS disk file into 
your virtual card punch: 


filedef inmove disk diskin file al 
filedef outmove punch 
movefile 


The result of these commands is effectively the same as if you had 
issued the command; 


punch diskin file (noheader 
The example does, however, illustrate the basic relationship between the 
FILEDEF and MOVEFILE commands. In addition to the MOVEFILE command, if 
the OS input data set is on tape or cards, you can use the TAPPDS or 
READCARD command to create CMS files. These are also discussed below. 


Note: The MOVEFILE command does not support data containing spanned 
records. 
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COPYING SEQUENTIAL DATA SETS FROM DISK: The MOVEFILE command copies a 
sequential OS disk data set from a read-only OS disk into an integral 
CMS file on a CMS read/write disk. You use FILEDEF commands to identify 
the input file disk mode and data set name: 

filedef inmove c1 dsn sales.manual 
the CMS output file's disk location and fileid: 

filedef outmove disk sales manual at 
and then you issue the MOVEFILE command: 

movefile 
COPYING PARTITIONED DATA SETS FROM DISK: The MOVEFILE command can copy 
partitioned data sets (PDS) into CMS disk files, and create separate CMS 
files for each member of the data set. You can have the entire data set 
copied, or you can copy only a selected member. For example, if you 
have a partitioned data set named ASSEMBLE.SOURCE whose members are 
individual assembler language source files, your input file definition 
might be: 

filedef inmove c1 dsn assemble source 

filedef inmove c1 dsn assemble.source 


To create individual CMS ASSEMBLE files, you would issue the output file 
definition as: 


filedef outmove disk gqprint assemble al 
Then use the PDS option of the MOVEFILE command: 
movefile (pds 
When the CMS files are created, the filetype on the output file 


definition is used for the filetype and the member names are used 
instead of the CMS filename you specified. 


If you want to copy only a single member, you can use the MEMBER 
option of the FILEDEF command: 
filedef inmove disk assemble source c (member qprint 
and omit the PDS option on the MOVEFILE command: 
movefile 


Figure 16 summarizes the various ways that you can create CMS files 
from OS data sets. 


Using CMS Libraries 


CMS provides three types of libraries to aid in OS program development: 
e Macro libraries contain macro definitions and/or copy files 


e Text, or program likraries contain relocatable object programs 
(compiler output) 
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e LOADLIB libraries contain link edit files (load modules) 


These CMS libraries are like OS partitioned data sets; each has a 
directory and members. Since they are not like other CMS files, you 
create, update, and use them differently than you do other CMS files. 
Although these library files are similar in function to OS partitioned 
data sets, OS macros should not be used to update them. Macro libraries 
are discussed below; text libraries are discussed under "TEXT Libraries 
(TXTLIBs)", and LOADLIB libraries are discussed under "Executing Members 
of OS Modules Libraries or CMS LOADLIBS". 


A CMS macro library has a filetype of MACLIB. You can create a MACLIB 
from files with filetypes of MACRO or COPY. A MACRO file may contain 
macro definitions; COPY files contain predefined source statements. 


(re as ae ae es 
| Input File: An OS sequential data set named: COMPUTE.TEST. RECORDS | 
| | 
| Source | C4%S Command Fxamples | CMS Output File { 
Se ee ee re | 
| Disk: | filedef indd c1 dsn compute test records | COMPUTE RECORDS A1 | 
| OS R/O | filedef outdd disk compute records a1 | | 
| C-—disk | movefile indd outdd | | 
l | 
| Tape: | filedef inmove tap1 (lrecl 80 | TEST RECORDS Atl | 
| 181 | filedef outmove disk test records al | | 
| | movefile | | 
| — oe | 
| | tappds newtest compute (nopds | NEWTEST COMPOTE At | 
I { 
| Cards | filedef cardin reader | COMPUTE CARDS Atl | 
| | filedef diskout disk compute cards a1 | | 
| | movefile cardin diskout | | 
| | 1 
| | creadcard compute test | COMPUTE TEST A1 | 
l =| 
| ee | 
| Input file: OS partitioned data set named: TEST.CASES | 
| Members named: SIMPLE, COMPLEX, MIXED | 
| 1 
| Source | CMS Command Examples | CMS Output File(s) | 
||_————————c“——_—— { 
| Disk: | filedef infile disk test cases cl | SIMPLE TESTCASE Al | 
| OS R/O | filedef outfile disk new testcase al | COMPLEX TESTCASE At | 
| C-—disk | movefile infile outfile (pds | MIXED TESTCASE | 
| I ( 
| | filedef in c1 dsn test cases (member simple | FILE RUN Atl | 
| | filedef run disk | | 
| | movefile in run | | 
| I 
| Tape: | tappds - testrun (tap2 | SIMPLE TESTRUN A1 { 
| 182 l | COMPLEX TESTRUN At { 
| { 


| { MIXED TESTRUN A1 


Figure 16. Creating CMS Files from OS Data Sets 
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When you want to assemble or compile a source program that uses macro 
or copy definitions, you must ensure that the library containing the 
code is identified before you invoke the compiler. Otherwise, the 
library is not searched. You identify libraries to be searched using the 
GLOBAL command. For example, if you have two MACLIBs that contain your 
private macros and copy files whose names are TESTMAC MACLIB and 
TESTCOPY MACLIB, you would issue the command: 


global maclib testmac testcopy 


The libraries you specify on a GLOBAL command line are searched in the 
order you specify then. A GLOBAL command remains in effect for the 
remainder of your terminal session, until you issue another GLOBAL 
MACLIB command or IPL CMS again. To find out what macro libraries are 
currently available for searching, issue the command: 


query maclib 
You can reset the libraries or the search order by reissuing the GLOBAL 
command. 


THE MACLIB COMMAND 


The MACLIB command performs a variety of functions. You use it to: 


Create the MACLIB (GEN function) 

Add, delete, or replace members (ADD, DEL, and REP functions) 
Compress the MACLIB (COMP function) 

List the contents of the MACLIB (MAP function) 


Descriptions of these MACLIB command functions follow. 
GEN Function: The GEN (generate) function creates a CMS macro library 
from input files specified on the command line. The input files must 
have filetypes of either MACRO or COPY. For example: 

maclib gen osmac access time put regequ 
creates a macro library with the file identifier OSMAC MACLIB A1 fron 
macros existing in the files with the file identifiers: 


ACCESS {MACRO|,TIME {MACRO|,PUT {MACRO),and REGEQU {MACRO 
COPY COPY COPY COPY 


If a file named OSMAC MACLIB Al already exists, it is erased. 


Assume that the files ACCESS MACRO, TIME COPY, PUT MACRO, and REGEQU 
COPY exist and contain macros in the following form: 


ACCESS MACRO TIME COPY PUT MACRO REGEQU COPY 
GET *COPY TTIMER PUT XREG 
TTIMER 
PUT *COPY STIMER YREG 
STIMER 


The resulting file, OSMAC MACLIB A1, contains the members: 


GET STIMER 
PUT PUT 
TTINER REGEQU 
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The PUT macro, which appears twice in the input to the command, also 
appears twice in the output. The MACLIB command does not’ check for 
duplicate macro names. If, at a later time, the PUT macro is requested 
from OSMAC MACLIB, the first PUT macro encountered in the directory is 
used. 


When COPY files are added to MACLIBs, the name of the library member 
is taken from the name of the COPY file, or from the *COPY statement, as 
in the file TIME COPY, above. Note that although the file REGEQU COPY 
contained two macros, they were both included in the MACLIB with the 
name REGEQU. When the input file is a MACRO file, the member name(s) are 
taken from macro prototype statements in the MACRO file. 


ADD Function: The ADD function appends new members to an existing macro 
library. For example, assume that OSMAC MACLIB A1 exists as created in 
the example in the explanation of the GEN function and the file DCB COPY 
exists as follows: 


*COPY DCB 

DCB macro definition 

*COPY DCBD 

DCBD macro definition If you issue the command: 
maclib add osmac dcb 


the resulting OSMAC MACLIB A1 contains the menbers: 


GET PUT 
PUT REGEQU 
TT IMER DCB 
STIMER DCBD 


REP Function: The REP (replace) function deletes the directory entry for 
the macro definition in the files specified. It then appends new macro 
definitions to the macro library and creates new directory entries. For 
example, assume that a macro library MYMAC MACLIB contains the nembers 
A, B, and C, and that the following command is entered: 


maclib rep mymacac 


The files represented by file identifiers A MACRO and C MACRO each have 
one macro definition. After execution of the command, MYMAC MACLIB 
contains members with the same names as' before, but the contents of A 
and C are different. 


DEL Function: The DEL (delete) function removes the specified macro name 
from the macro library directory and compresses the directory so there 
are no unused entries. The macro definition still occupies space in the 
library, but since no directory entry exists it cannot be accessed or 
retrieved. If you attempt to delete a macro for which two macro 
definitions exist in the macro library, only the first one encountered 
is deleted. For example: 


maclib del osmac get put ttimer dcb 
deletes macro names GET, PUT, TTIMER, and DCB from the directory of the 
macro library named OSMAC MACLIB. Assume that OSMAC exists as in the ADD 
function example. After the above command, OSMAC MACLIB contains the 
following members: 


STIMER 
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COMP Function: Execution of a MACLIB command with the DEL or REP 
functions can leave unused space within a macro library. The COMP 
(compress) function removes any macros that do not have directory 
entries. This function uses a temporary file named MACLIB CMSUT1. For 
example, the command: 


maclib comp mymac 
compresses the library MYMAC MACLIB. 


MAP Function: The MAP function creates a list containing the name of 
each macro in the directory, the size of the macro, and its position 
within the macro library. If you want to display a list of the members 
of a MACLIB at the terminal, enter the command: 


Maclib map mylib (term The default option, DISK, creates a file on 
your A-disk, which has a filetype of MAP and a filename corresponding to 
the filename of the MACLIB. If you specify the PRINT option, the list 
is spooled to your virtual printer. 


Note: TERM and PRINT options will erase the old MAP file. 


Manipulating MACLIB Members 


The following CMS commands have MEMBER options, which allow you’ to 
reference individual members of a MACLIB: 


PRINT (to print a member) 

PUNCH (to punch a member) 

TYPE (to display a member) 

FILEDEF (to establish a file definition for a member) 


You can use the CMS Editor to create MACRO and COPY files and then 
use the MACLIB command to place the files ina library. Once they are 
in a library, you can erase the original files. 


To extract amember froma macro library, you can use either the 
PUNCH or the MOVEFILE command. If you use the PUNCH command you can 
spool your virtual card punch to your own virtual reader: 

cp spool punch to * 
Then punch the member: 

punch testmac maclib (member get noheader 
and read it back onto disk: 

readcard get macro 
In the above example, the member was punched with the NOHEADER option of 
the PUNCH command, so that a name could be assigned on the READCARD 
command line. If a header card had been created for the file, it would 
have indicated the filename and filetype as GET MEMBER. 

If you use the MOVEFILE command, you must issue a file definition for 
the input member name and the output macro or copy name before entering 
the MOVEFILE command: 

filedef inmove disk testcopy maclib (member enter 


filedef outmove disk enter copy a 
novefile 
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This example copies the member ENTER from the macro library TESTCOPY 
MACLIB into a CMS file named ENTER COPY. 


When you use the PUNCH or MOVEFILE commands to extract nembers fron 
CMS MACLIBs, each member is followed by a // record, which is a MACLIB 
delimiter. You can edit the file and use the DELETE subcommand to 
delete the // record. 


If you wish to move the complete MACLIB to another file, use the 
COPYFILE command. 


system MACLIBs 


The macro libraries that are on the system disk contain CMS and OS 
assembler language macros that you may want to use in your programs: 


e CMSLIB MACLIB contains the CMS macros. 


e OSMACRO MACLIB contains the OS macros that CMS supports or simulates 
or those that require no CMS support. 


e OSMACRO1 MACLIB contains the macros CMS does not support or simulate. 
(You can assemble programs in CMS that contain these macros, but you 
must execute them in an OS virtual machine.) 


e TSOMAC MACLIB contains TSO macros. 
e DOSMACRO MACLIB contains macros used in CMS/DOS. 


To obtain a list of the macros in any of these libraries, use the MAP 
function of the MACLIB command. 


USING OS MACRO LIBRARIES 


If you want to assemble source programs that contain macro statements 
that are defined in macro libraries on your OS disks, you can use the 
FILEDEF command to identify them to CMS so that you can name them when 
you issue the GLOBAL command. 

For example, the commands: 


filedef cmslib disk temp maclib c dsn test asm macros 
global maclib temp 


allow you to access the macro library TEST.ASM.MACROS on the OS disk 
accessed as your C-disk. 


When you issue a FILEDEF command for an assembler language macro 
library you must use a ddname of CMSLIB and you must provide a CMS file 
identifier for the OS data set. In the example above, the OS macro 
library TEST.ASM.MACROS is given the CMS file identifier TEMP MACLIB. 


If you want to use more than one OS macro library you must issue a 
FILEDEF command for each library using the ddname CMSLIB and specifying 
the CONCAT option. For example: 


filedef cmslib disk asp1 maclib * dsn asp1l.macros.r1 (concat recfm fb block 3360 lrecl 80 
filedef cmslib disk asp2 maclib * dsn asp2.macros.r1 (concat 

filedef cmslib disk sys1 maclib * (concat 

global maclib asp1 asp2 sys1 osmacro caslib 
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The GLOBAL command establishes the search order of the libraries as: 
ASP1.MACROS.R1, ASP2.MACROS.R1, S¥S1.MACLIB, OSMACRO MACLIB, and CMSLIB 
MACLIB. Note that the third likrary specified is entered in an 
abbreviated form. You can use this form when the data set name of the 
Macro library has only two qualifiers and the second gualifier is 
MACLIB; thus, the equivalency is established between SYS1.MACLIB and the 
CMS file identifier SYS1 MACLIB. 


The file format information describes the macro libraries to CMS; 
when you are concatenating OS macro libraries, they must all be in the 
same format, since the options entered on the first FILEDEF command are 
applied to all the libraries. 


Also, if you want to use the FILEDEF option CONCAT, the first FILEDEF 
command for concatenated macro libraries should describe the first 
library in the GLOBAL command. When a concatenated macro library is 
closed after use, the CMS filename in the FCB is restored to the first 
name in the global list. If this is not the one specified on the 
Original FILEDEF, subsequent use may cauSe errors. Reissue the FILEDEF 
command. 


If you are using only one OS macro library in addition to CMS MACLIBs 
you can enter: 


filedef cmslib disk 1ib1 maclib * dsn sys1.maclib 
global maclib 1ib1 cmslib 


To identify libraries for use with the language processors, you must 
use the ddname SYSLIB. 


Using the CONCAT option for the first FILEDEF (with PERM option) for 
concatenated libraries may cause errors if the FILEDEF is not cleared 
before subsequent use of FILEDEF. 


Using OS Macro Simulation Under CMS 


CMS provides routines that simulate the OS functions required to support 
OS language processors and user-written programs. CMS functionally 
Simulates the OS macros in such away that equivalent results are 
presented to programs executing under CMS. 


Figure 17 lists the OS macros and their functions that CMS partially 
or completely simulates. The macros that are listed as "effective 
no-op" and "no-op" are macros that are not supported in CMS; you can 
assemble programs that contain these macros. However, when you execute 
them in CMS, the macro functions are not performed. To execute these 
programs, you must run them in an OS virtual machine. 


For a more detailed description of how CMS simulates the functions of 
these macros, and to see whether any particular function of a macro is 
not supported, see the VM/SP System Programmer's Guide. 


OS DATA MANAGEMENT SIMULATION 


A CMS file produced by an OS program cunning under CMS and written ona 
CMS disk, has a different format than that of an OS data set produced by 
the same OS program running under OS and written onanoOS disk. The 
data is the same, but, the format is different. CMS can read, write, or 
update any OS data that resides on a CMS disk. 
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Terminate processing 


Effective LINK 


Build a directory list for a PDS 
Back up a record on a tape or disk 


Effective no—-op 


Verify READ/WRITE macro completion 


Effective no—-op 


Deactivate a data file 


Construct a data control block 
Generate a DSECT for a data control block 


Delete a loaded 
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Obtain device—type characteristics 


Effective no-op 


phase 
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| Macro ISvc No.| Function | 
| | l d 
|] TCLOSE Jj 23 | Temporarily deactivate a data file | 
| TGET/TPUT | 93 | Read or write a terminal line | 
| TIME | 11 | Get the time of day | 
| TRKBAL | 25 | no—-op | 
| TTIMER | 46 | Access or cancel timer { 
| WAIT |} 01 | Wait for an I/O completion | 
| WRITE | - | Write system—-record data [ 
| WTO/WTOR | 35 | Communicate with the terminal [ 
| xcTL | 07 | Delete, then link control to another | 
[ [ | load phase | 
|  XDAP i oo | Read or write direct access volumes | 


Figure 17. OS Macros Simulated by CMS (Part 2 of 2) 


Assembling Programs in CMS 


To assemble assembler language source programs into object module 
format, you can use the ASSEMBLE command, and specify assembler options 
on the command line; for example: 


assemble myfile (print 


assembles a source program named MYFILE ASSEMBLE and directs the output 
listing to the printer. All of the ASSEMBLE command options are listed 
in the VM/SP CMS Command and Macro Reference. 


When you invoke the ASSEMBLE command specifying a file with the 
filetype of ASSEMBLE, CMS searches all of your accessed disks, using the 
standard search order, until it locates the specified file. When the 
assembler creates its output listing and text deck, it creates files 
with filetypes of LISTING and TEXT, and writes them onto disk according 
to the following priorities: 


1. If the source file is on a_ read/write disk, the TEXT and LISTING 
files are written onto that disk. 


2. If the source file is on a read-only extension of a read/write 
disk, the TEXT and LISTING files are written onto the parent disk. 


3. If the source file is on any other read-only disk, the TEXT and 
LISTING files are written onto the A-disk. 


G“&. If none of the above choices are available, the command is 
terminated. 


In all of the above cases, the TEXT and LISTING files have a filename 
that is the same as the input ASSEMBLE file. 


The input and output files used by the assembler are assigned by 
FILEDEF commands that CMS issues internally when the assembler is 
invoked. If you issue a FILEDEF command using one of the assembler 
ddnames before you issue the ASSEMBLE command, you can override the 
default file definitions. 
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The ddname for the source input file (SYSIN) is ASSEMBLE. If you 
enter: 


filedef assemble reader 
assemble sample 


then the assembler reads your input file from your card reader, and 
assigns the filename SAMPLE to the output TEXT and LISTING files. 


You could assemble a source file directly from anoOS disk by 
entering: 


filedef assemble disk myfile assemble b4 dsn os source file 
assemble nyfile 


In this example, the CMS file identifier MYFILE ASSEMBLE is assigned to 
the data set OS.SOURCE.FILF and then assembled. 


LISTING and TEXT are the ddnames assigned to the SYSPRINT and SYSLIN 
output of the assembler. You might assign file definitions to override 
these defaults as follows: 


filedef listing disk assemble listfile a 
filedef text disk assemble textfile a 
assemble nyfile 


In this example, output from the assembly of the file, myfile ASSEMBLE, 
is written to the files, ASSEMBLE LISTFILE and ASSEMBLE TEXTFILE. 


The ddnames PUNCH and CMSLIB are used for SYSPUNCH and SYSLIB data 
sets. PUNCH output is produced when you use the DECK option of the 
ASSEMBLE command. The default file definition for CMSLIB is the macro 
library CMSLIB MACLIB, but you must still issue the GLOBAL command if 
you want to use it. 


Executing Programs 


After you have assembled or compiled a source program you can execute 
the TEXT files that were produced by the assembly or compilation. You 
may not, however, be able to execute all your OS programs directly in 
CMS. There are a number of execution-time restrictions placed on your 
virtual machine by VM/SP. You cannot execute a program that uses: 


e Multitasking 

e More than one partition 

e Teleprocessing 

e ISAM macros to read or write files 
e Sets the EC mode bit in the PSW 


The above is only a partial list, representing those restrictions with 
which you might be concerned. For a complete list of restrictions, see 
the VM/SP Planning and System Generation Guide. 


EXECUTING TEXT FILES 


TEXT files, in CMS, are relocatable, and can be executed simply by 
loading them into virtual storage with the LOAD command and using the 
START command to begin execution. For example, if you have assembled a 
source program named CREATE, you have a file named CREATE TEXT. You can 
issue the command: 
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load create 


which loads the relocatable object file into storage, and then, to 
execute it, you can issue the START command: 


start 


In the case of a simple program, as in the above example, you can 
load and begin execution with a single command line, using the START 
option of the LOAD command: 


load create (start 


When you issue the START command or LOAD command with the START 
option, control is passed to the first entry point in your program. If 
you have more than one entry point and you want to begin execution at an 
entry point other than the first, you can specify the alternate entry 
point or CSECT name on the START command: 


start create2 


When you issue the LOAD command specifying the filename of a TEXT file, 
CMS searches all of your accessed disks for the specified file. 


If your program expects a parameter list to be passed (via register 
1), you can specify the arguments on the START command line. If you 
enter arguments, then you must specify the entry point: 


start * namet 


When you specify the entry point as an asterisk (*) it indicates that 
you want to use the default entry point. 


Defining Input and Output Files 


You can issue the FILEDEF command to define input and output files any 
time before you begin program execution. You can issue all your file 
definitions before loading any TEXT files, or issue them during the 
loading process. You can find out what file definitions are currently 
in effect by issuing the FILEDEF command with no operands: 


filedef 


You can also use the FILEDEF operand of the QUERY command. 


TEXT LIBRARIES (TXTLIBS) 


You may want to keep your TEXT files in text libraries, that havea 
filetype of TXTLIB. Like MACLIBs, TXTLIBs have a directory and members. 
TXTLIBS are created and modified by the TXTLIB command, which has 
functions similar to the MACLIB command: 


The GEN function creates the TXTLIB. 

The ADD function adds members to the TXTLIB. 

The DEL function deletes members and compresses the TXTLIB. 
The MAP function lists members. 


There is no REP function; you must use a DEL followed by an ADD to 
replace an existing member. The CMS commands that recognize MACLIBS as 
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special filetypes also recognize TXTLIBs, and allow you to display, 
print, or punch TXTLIB members. 


The TXTLIB command reads the object files as it writes them into the 
library, and creates a directory entry for each entry point or CSECT 
Mame. If you have a TEXT file named MYPROG, which has a single routine 
named BEGIN, and create the TXTLIB named TESTLIB as follows: 


txtlib gen testlib myprog 


TESTLIB contains no entry for the name MYPROG; you must’ specify the 
membername BEGIN to reference this TXTLIB member. 


When you want to load members of TXTLIBS into storage to execute then 
(just as you execute TEXT files), you must issue the GLOBAL command to 
identify the TXTLIB: 


global txtlib testlib 
load begin (start 
When you specify more than one TXTLIB on the GLOBAL command line, the 
order of search is established for the TXTLIBs. However, if the AUTO 
option is in effect (it is the default), CMS searches for TEXT files 
before searching active TXTLIBs. 


When the TXTLIB command processes a TEXT file, it writes an LDT 
{loader terminate) card at the end of the TEXT file, so that when a load 
request is issued for a TXTLIB member, loading terminates at the end of 
the member. If you add OS linkage editor control statements to the TEXT 
file (using the CMS editor) before you issue the TXTLIB command to add 
the file to a TXTLIB, the control statements are processed as follows: 


NAME: A NAME statement causes the TXTLIB command to create the directory 
entry for the member using the specified name. Thereafter, when you want 
to load that member into storage or delete it from the TXTLIB you must 
refer to it by the name specified on the NAME statement. 


The loader does not use name cards to resolve entry points. It is 
important that the name on the name card be the same as the name on the 
CSECT or entry card. This will ensure that the loader will find the 
correct text deck and loader tables (any external references) will be 
resolved with the entry point. If the names differ, the loader will 
load the test deck based on the name card (or file name). However, the 
loader tables will be set up according to entry or CSECT cards 
encountered during the load. Any external reference using the name fron 
the name card will be resolved as zeros. See the section “Resolving 
External References" for more detailed information. 


ENTRY: If you use an ENTRY statement, the entry point you specify is 
validated and checked for a duplicate. If the entry point name is valid 
and there are no duplicates in the TEXT file, the entry name is written 
in the LDT card. Otherwise, an error message is issued. When this 
member is loaded, execution begins at the entry point specified. (See 
the following "Determining Program Entry Points.") 


ALIAS: An entry is created in the directory for the ALIAS name you 
specify. A maximum of 16 alias names can be used in a single text deck. 
You may load the single member and execute it by referring to the alias 
hame, but you cannot use the alias name as the object of V-type address 
constant (VCON), because the address of the member cannot be resolved. 


SETSSI: Information you specify on the SETSSI card is written in bytes 
26 through 33 of the LDT card. 
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All other OS linkage editor control statements are ignored by the 
TXTLIB command and written into the TXTLIB member. When you attempt to 
load the member, the CMS loader flags these cards as invalid. 


RESOLVING EXTERNAL REFERENCES 


The CMS loader loads files into storage as a result of a LOAD or INCLUDE 
command. When a file is loaded, the loader checks for unresolved 
references; if there are any, the loader searches your disks for TEXT 
files with filenames that match the external entry name. When it finds a 
match, it loads the TEXT file into storage. If a TEXT file is not found, 
the loader searches any available TXTLIBs for members that match; if a 
Match is found, it loads the member. 


If there are still unresolved references, for example, if you load a 
program that calls routines PRINT and ANALYZE but the loader cannot 
locate them, you receive the message: 


THE FOLLOWING NAMES ARE UNDEFINED: 
PRINT 
ANALYZE 


You can issue the INCLUDE command to load additional TEXT files or 
TXTLIB members into storage so the loader can resolve any remaining 
references. For example, if you did not identify the TXTLIB' that 
contains the routines you want to call, you may enter the GLOBAL command 
followed by the INCLUDE command: 


global txtlib newlib 
include print analyze (start 


A failure to resolve external references might occur if you have TEXT 
files with filenames that are different from either the CSECT names or 
the entry names; You must explicitly issue LOAD and INCLUDE commands 
for these files. 


At execution time, if there are still any unresolved references, 


their addresses are all set to 0 by the loader, so any attempt to 
address them in a program may result in a program check. 


The LOAD and INCLUDE Commands 


The INCLUDE command has the same format and option list (with one 
exception) as the LOAD command. The main difference is that when you 
issue the INCLUDE command the loader tables are not reset; if you issue 
two LOAD commands in succession, the second LOAD command cancels the 
effect of the first, and the pointers to the files loaded are lost. 


Conversely, the INCLUDE command, which you must issue when you want 
to load additional files into storage, should not be used unless you 
have just issued a LOAD command. You may specify as many INCLUDE 
commands as necessary following a LOAD command to load files into 
storage. 
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CONTROLLING THE CMS LOADER 


The LOAD and INCLUDE commands allow you to specify a number of options. 
You can: 


e Change the entry point to which control is to be passed when 
execution begins (RESET option). 


e Specify the location in virtual storage at which you want the files 
to be loaded (ORIGIN option). 


e Control how CMS resolves references and handles duplicate CSECT names 
(AOTO, LIB, and DUP options). 


e Clear storage to binary zeros before loading files (CLEAR option). 
Otherwise CMS does not clear user storage. 


When the LOAD and INCLUDE commands execute, they produce a load map, 
indicating the entry points loaded and their virtual storage locations. 
You may find this load map useful in debugging your programs. If you do 
not specify the NOMAP option, the load map is written onto your A-disk, 
in a file named LOAD MAP A5. Each time you issue the LOAD command, the 
old file LOAD MAP is erased and the new load map replaces it. If you do 
not want to produce a load map, specify the NOMAP option. 


You can find details about these, and other options under the 
discussion of the LOAD command in VM/SP CMS Command and Macro Reference. 


Loader Control Statement 


In addition to the options provided with the LOAD and INCLUDE commands 
that assist you in controlling the execution of TEXT files, you can also 
use loader control statements. These can be inserted in TEXT files, 
using the CMS editor. The loader control statements allow you to: 


e Set the location counter to specify the address at which the next 
TEXT file is to be loaded (SLC statement). 


e Modify instructions and constants ina MfTEXT file, and change the 
length of the TEXT file to accomodate modifications (Replace and 
Include Control Section statements). 


e Change the entry point (ENTRY statement). 


e Nullify an external reference so that it does not receive control 
when it is called, and you do not receive an error message when it is 
encountered (LIBRARY statement). 


These statements are also described under the LOAD command in VM/SP CMS 
Command and Macro Reference. 


Determining Program Entry Points 


RD eae CAR 


When you load a single TEXT file or a TXTLIB member into storage for 
execution, the default entry point is the first CSECT name in the object 
file loaded. You can specify a different entry point at which to start 
execution either on the LOAD (or INCLUDE) command line with the RESET 
option: 
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load myprog (reset beta 


where BETA is the alternate entry point of your program, or you can 
specify the entry point on the START command iine: 


start beta 


When you load multiple TEXT files (either explicitly or implicitly, 
by allowing the loader to resolve external references), you also have 
the option of specifying the entry point on the LOAD, INCLUDE, or START 
command lines. 


If you do not specifically name an entry point, the loader determines 
the entry point for you, according to the following hierarchy: 


1. An entry point specified on the START command 


2. The last entry specified with the RESET option on a LOAD or INCLUDE 
command 


3. The name on the last ENTRY statement that was read 


4. The name on the last LDT statement that contained an entry name 
that was read 


5. The name on the first assembler- or compiler-produced END statement 
that was read 


6. The first byte of the first control section loaded 


For example, if you load a series of TEXT files that contain no 
control statements, and donot specify an entry point on the LOAD, 
INCLUDE, or START commands, execution begins with the first file that 
you loaded. If you want to control the execution of program subroutines, 
you should be aware of this hierarchy when you load programs or when you 
place them in TXTLIBs. 


An area of particular concern is when you issue a dynamic load (with 
the OS LINK, LOAD, or XCTL macros) from a frogran, and you call members 
of CMS TXTLIBs. The CMS loader determines the entry point of the called 
program and returns the entry point to your program. If a TXTLIB nember 
that you load has a VCON to another TXTLIB member, the LDT card from the 
second member may be the last LDT card read by the loader. If this LDT 
card specifies the name of the second member, then CMS may return that 
entry point address to your program, rather than the address of the 
first member. 


CREATING PROGRAM MODULES 


When your programs are debugged and tested, you can use the LOAD and 
INCLUDE commands, in conjunction with the GENMOD command, to create 
program modules. A module is a nonrelocatable file whose external 
references have been resolved. In CMS, these files must have a filetype 
of MODULE. 


To create a program module, load the TEXT files or TXTLIB members 
into storage and issue the GENMOD command: 


load create analyze print 
genmod process 
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In this example, PROCESS is the filename you are assigning the 
module; it will have a filetype of MODULE. You could use any name; if 
you use the name of an existing MODULE file, the old one is replaced. 


To execute the program composed of the source files CREATE, ANALYZE, 
and PRINT, enter: 


process 


If PROCESS requires input and/or output files, you will have to define 
these files before PROCESS can execute properly; if PROCESS expects 
arguments passed to it, you can enter them following the MODULE nane; 
for example: 


process test1 


For more information on creating program modules, see “Section 13. 
Programming for the CMS Environment." 


USING EXEC PROCEDURES 


During your program development and testing cycle, you may want to 
create EXEC procedures to contain sequences of CMS commands’ that you 
execute freguently. For example, if you need a number of MACLIBs, 
TXTLIBs, and file definitions to execute a particular program, you might 
have an EXEC procedure as follows: 


&CONTROL ERROR TIME 

GSERROR &EXIT &ERETCODE 

GLOBAL MACLIB TESTLIB OSMACRO OSMACRO1 
ASSEMBLE TESTA 

PRINT TESTA LISTING 

GLOBAL TXTLIB TESTLIB PROGLIB 
ACCESS 200 E 

&BEGSTACK 

OS.TEST3.STREAM.BETA 

SEND 

FILEDEF INDD1 E DSN ? 

FILEDEF INDD2 READER 

FILEDEF OUTFILE DISK TEST DATA Al 
LOAD TESTA (START 

SIF &RETCODE = 100 &GOTO -RET100 
SIF &SRETCODE = 200 &GOTO -RET200 
SEXIT &S&RETCODE 

~RET100 &SCONTINUE 


-RET200 SCONTINUE 


The & CONTROL and &ERROR control statements in the EXEC. procedure 
ensure that if an error occurs during any part of the EXEC, the 
remainder of the EXEC does not execute, and the execution summary of the 
EXEC indicates the command that caused the error. 


Note that for the FILEDEF command entered with the DSN ? _ operand, 
you must stack the response before issuing the FILEDEF command. In this 
example, since the OS data set name has more than eight characters, you 
Must use the &BEGSTACK control statement to stack it. If you’ use the 
&STACK control statement, the EXEC processor truncates all words to 
eight characters. 
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When your program is finished executing, the EXEC special variable 
SRETCODE indicates the contents of general register 15 at the time the 
program exited. You can use this value to perform additional steps in 
your EXEC procedure. Additional steps are indicated in the preceding 
example by ellipses. 


For detailed information on creating EXEC procedures, see "Part 3. 
Learning to Use EXECs." 


Executing Members of OS Module Libraries or CMS LOADLIBS 


The OS relocating loader allows the user to load a member of a CMS 
LOADLIB or an OS module library on an OS formatted disk. The OS LINK, 
LOAD, ATTACH, and XCTL macros are supported. In addition, the OSRUN 
command (which generates a LINK SVQ) is supported to provide for loading 
and executing members directly from the console. 


For macros, the libraries specified in the LOADLIB global list are 
searched. If the requested member is not found, CMS looks for a TEXT 
file by that name; then, if still not found, the TXTLIBs specified in 
the TXTLIB global list are searched for the member name. 


For the OSRUN command, the libraries specified in the LOADLIB global 
list are searched. If the member is not found and the user has a 
$SYSLIB LOADLIB file, it is searched for the member name. (TEXT and 
TEXTLIBs are not considered by OSRON.) 


A FILEDEF command must define any OS module libraries from which 
members are to be loaded. The DDNAME specified must be $SYSLIB. The 
filename can be any name, but it must correspond to the name stated in 
the GLOBAL statement; the filetype must be LOADLIB. To define more than 
one library with the same DDNAME, use the CONCAT option of the FILEDEF 
command. Any library to be searched (either CMS LOADLIB or OS module 
library) must be specified in the GLOBAL LOADLIB statement. The data 
set with the largest block size should be specified first (both in the 
FILEDEF and in the GLOBAL list). CMS files do not require a file 
definition, but if used, the file with the largest block size should be 
specified first. The GLOBAL list determines the order in which the 
libraries are searched. 


The LKED command is used to create a CMS LOADLIB. For example: 
LKED TESTFILE 
takes a CMS TEXT file with the filename of TESTFILE and creates a file 
named TESTFILE LOADLIB. For more information on input to the LKED 
command refer to the section, "Specifying Input to the LKED command." 
The LOADLIB the LKED TESTFILE example creates is an OS simulated PDS 
Hamed TESTFILE LOADLIB and contains one member named TESTFILE. To 
execute TESTFILE using the OSRUN command, the GLOBAL command nust be 
used. For example: 
GLOBAL LOADLIB TESTFILE 


The OSRUN command causes the TESTFILE member of the TESTFILE loadlib to 
be loaded, relocated, and executed: 


OSRUN TESTFILE 


If the module to be executed resides in an OS module library on an OS 
formatted disk, the disk must be accessed and the library must be 
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defined (via the FILEDEF command) to make it known to CMS. For example, 
if SYS1.TESTLIB is a library on an OS disk and contains a member called 
TEST1, the following would be required to execute TEST1: 


ACCESS 250 B (where 250 is the address of the OS disk) 

FILEDEF $SYSLIB DISK OSLIB LOADLIB B DSN SYS1 TESTLIB 
(DSORG PO RECFM U BLOCK 7294 

GLOBAL LOADLIB OSLIB 

OSRUN TEST1 


The LOADLIB files on OS disks can be concatenated with each other and 
with CMS LOADLIB files by coding the FILEDEF command with the CONCAT 
option. For example, two OS files and a CMS LOADLIB are searched for 
TEXT with the following commands: 


ACCESS 250 B (if 250 is the address of the OS disk) 
FILEDEF $SYSLIB DISK OSLIB LOADLIB DSN SYS1 LIB1 
(DSORG PO RECFM U BLOCK 7294) 

FILEDEF $SYSLIB DISK MYLIB LOADLIB B DSN SYS1 LIB2 (CONCAT) 

GLOBAL LOADLIB OSLIB MYLIB CMSLIB 

OSRUN TEST 
Note: The first FILEDEF command for $SYSLIB must describe the first 
library filename in the GLOBAL list. Its attribute will be used when 
the libraries are searched. It is advisable not to code the CONCAT 
option on the first FILEDEF command so that it clears all previous 
FILEDEFs for that ddname. 


The LOADLIB command provides the utility necessary to maintain the 
CMS LOADLIBs. The following functions are provided: 


COPY Copy members from one LOADLIB to another 
Merge complete LOADLIBs 
Copy with SELECT or EXCLUDE 


COMPRESS Compress a CMS LOADLIB 
LIST LIST members of a CMS LOADLIB 


For more detailed information on the LKED, GLOBAL, OSRUN, and LOADLIB 
commands, refer to the VM/SP CMS Command and Macro Reference. 


Specifying Input to the LKED Command 


Primary LKED input is a data set known to the linkage editor as SYSLIN, 
which can be described in the FNAME operand of the LKED command. The 
filetype of the input file named in the command line must be TEXT. 
Optionally, you can override the FNAME operand by issuing a FILEDEF that 
defines SYSLIN as the ddname of an alternate primary input source. If 
your alternate input is a CMS file, the choice of filetype is 
unrestricted. The contents of the SYSLIN dataset may be: 


1. Object text such as assembler or compiler output 
2. Linkage editor control statements 
3. A combination of object text and control statements. 


Linkage editor control statements can be inserted before, between, and 
after object modules and other control statements. Editing procedures 
can be used to construct files to meet your requirements. Linkage 
editor INCLUDE statements may be used to designate explicitly the 
following files or file members as secondary linkage editor input: 
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1. CMS TEXT files 

2. CMS TEXTLIB files 

3. CMS LOADLIB files 

4. Members of OS object libraries 
5. Members of OS load libraries 


A FILEDEF must be issued before the LKED command to define a unique 
ddname for each file to be included as secondary linkage editor input. 
An INCLUDE statement in the SYSLIN dataset must specify the ddname 
assigned to the file by your FILEDEF. For library files, the statement 
must also specify all members of the library that are to be included as 
input. The use of all FILEDEF commands and INCLUDE statements’ to 
identify input files is shown in the following examples. 


CMS commands: 


FILEDEF LIBDEF DISK MYLIB TXTLIB B 
FILEDEF TXTDEF DISK MYFILE TEXT C 


SYSLIN input: 


INCLUDE LIBDEF (CSECT1,CSECT2) 
INCLUDE TXTDEF 


INCLUDE statements must begin in column 2. The applicable statement 
formats are described in the OS/VS Linkage Editor and Loader, GC26-3813. 


Automatic library search is available for either CMS or OS type 
library members if the FILEDEF for the dataset to be searched specifies 
SYSLIB as the ddnane. Additional libraries can be _ selected for 
automatic search by placing linkage editor LIBRARY statements in your 
SYSLIN input file. Each library statement must contain the associated 
ddname and a list of members within the library to be included in the 
search. A FILEDEF must be issued before the LKED command to assign a 
unigue ddname to each dataset to be searched. The library search 
conducted during a single linkage editor execution is limited to either 
object-type or load-type modules and may not combine both types. The 
CONCAT option of the FILEDEF command is not valid for LKED input 
datasets. To expand the use of the sutomatic SYSLIB search, the user 
may combine the menbers of several CMS libraries into a single composite 
library. The automatic search facility applies to CMS TXTLIBs and 
LOADLIBs and to OS object libraries and LOAD libraries. The following 
example shows FILEDEF commands and SYSLIN input for an automatic library 
search. 


CMS commands: 

FILEDEF SYSLIB DISK SEARCH1 TXTLIB B 

FILEDEF LIBDEFA DISK SEARCH2 TXTLIB c 

FILEDEF LIBDEF DISK OSTEXT LIBRARY D DSN OBJMODS 
SYSLIN input: 


LIBRARY LIBDEFA (CSECT1,CSECT2) 
LIBRARY LIBDEFB (MEMBER1, MEMBER2) 


LIBRARY statements must begin in column 2. The GLOBAL command is not 
needed to identify linkage editor input libraries. For LOADLIB input to 
the linkage editor, the RECFM U option of the FILEDEF command must be 
specified. 
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Section 9. Developing DOS Programs Under CMS 


You can use CMS to create, compile, execute and debug DOS programs 
written in assembler, COBOL, PL/I or RPG-II programming languages. CHS 
Simulates many functions of the Disk Operating System VSE/AF so that you 
can use the interactive facilities of VM/SP to develop your programs, 
and then execute them in a DOS virtual machine. 


This section tells you how to use the CMS/DOS environment. It 
describes the CMS commands you can use to manipulate DOS disks and DOS 
files and CMS/DOS commands you can use to simulate the functions of 
VSE/AF: 


The CMS/DOS environment 

Using DOS files on DOS disks 

Using the ASSGN command 

Using the DLBL command 

Using DOS libraries in CMS/DOS 

Using macro libraries 

DOS assembler language macros supported 
Assembling source programs 

Link-editing programs in CMS/DOS 
Executing programs in CMS/DOS 


For a practice terminal session using the commands and techniques 
presented in this section, see “Appendix D: Sample Terminal Sessions." 


A Word About Terminology 


CMS/DOS is neither CMS nor is it DOS; it is a composite, and its 
vocabulary contains both CMS and DOS terms. CMS/DOS performs many of 
the same functions as DOS, but where, under DOS, a function is initiated 
by a control card, in CMS it is initiated by a command. Many CMS/DOS 
commands, therefore, have the same names as the DOS control statenent 
that performs the same function. In those cases where the control 
statement you would use in DOS and the command you use in CMS are 
different, the differences are explained. For the most part, whenever a 
term that is familiar to you as a DOS term is used, it has’ the sane 
meaning to CMS/DOS, unless otherwise indicated. 


CMS/DOS support in VM/SP is based on the VSE/AF program product. The 
term DOS, however, continues to be used in a general sense and, in the 
discussion that follows, refers to the VSE/AF program product. 


The CMS/DOS Environment 
After you have loaded CMS into your virtual machine you can enter the 
CMS/DOS environment by issuing: 


set dos on 
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If you want to access a DOS system residence volume during your CMS/DOS 
terminal session, you should link to and access the disk that contains 
the DOS SYSRES before you issue the SET command. For example, if you 
Share the system residence volume with other users and it is in your 
directory at virtual address 390, you would issue the command: 


access 390 g 
and then issue the SET command as follows: 
set dos on g 


to indicate that the SYSRES is located on your G-disk. If you are going 
to use the CMS/DOS librarian facilities to access any of the libraries 
on the system residence volume, you must enter the CMS/DOS environment 
this way. 


If you are using CMS exclusively for DOS applications, you could put 
the ACCESS and SET DOS ON commands in your PROFILE EXEC. 


If you are going to use access method services functions in CMS/DOS, 
or execute functions that read or write VSAM data sets, you must use the 
VSAM option of the SET DOS ON command: 


set dos on g (vsan 


When you are using CMS/DOS, you can use your virtual machine just as 
you would if you were in the CMS environment; but you cannot execute any 
CMS commands or program modules that load and/or use OS macros. The 
SCRIPT command, for example, uses OS macros, and is therefore invalid in 
the CMS/DOS environment. 


You have, however, in addition to the CP and CMS commands available, 
a series of commands that simulate VSE/AF functions. Except for the 
DLBL and DOSLIB commands, these commands or operands should only be 
issued in the CMS/DOS environment. 


The CMS/DOS commands are summarized in Figure 18. 
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Command 


ASSGN 


DLBL 


DOSLIB 


DOSLKED 


DSERV 
NOSPLI 


ESERV 


FCOBOL 


FETCH 


GLOBAL 


LISTIO 


OPTION 


QUERY 


PSERV 


RSERV 


SET 


SSERV 
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Function 


Relates system and programmer logical units to physical 
devices. 


Relates a program DDname (filename) to a real disk file 
so you can perform input/output operations on it. 


Lists or deletes phases from a CMS/DOS phase library, 
or compresses the library. 


Link—edits CMS TEXT files or DOS phases from system or 
private relocatable libraries. 


Displays the directories of DOS libraries. 
An EXEC procedure that invokes the DOS/VS PL/I compiler. 


An EXEC procedure that invokes the ESERV utility 
functions on edited assembler language macros. 


An EXEC procedure that invokes the DOS/VS COBOL 
compiler. 


Loads executable phases from a DOSLIB or DOS library 
into storage for execution, and optionally starts 
execution. 


When you want DOSLIBs searched for executable phases 
or macro libraries searched for macro definitions, you 
must identify them with the GLOBAL command. 


Displays the current assignments of system and 
programmer logical units, and optionally creates an 
EXEC file to contain the information. 


Sets or changes the options in effect for the DOS/VS 
COBOL compiler. 


Use QUERY command operands to list current DLBL 
definitions (QUERY DLBL), to determine whether or not 
you are in the CMS/DOS environment (QUERY DOS), the 
setting of the UPST byte (QUERY UPSI), the DOSLIBs 
identified by GLOBAL commands (QUERY DOSLIB or 

Or QUERY LIBRARY), the current number of lines per 
page (QUERY DOSLNCNT), which options are in 

effect for the COBOL compiler (QUERY OPTION), or 

to find out whether you have set a virtual partition 
Size (QUERY DOSPART). 


Creates CMS files with a filetype of PROC from the 
VSE/AF procedure library, or displays, prints or 
punches procedures. 


Copies a relocatable module from a DOS library and 
places it in a CMS file with a filetype of TEXT, 
or displays, prints, or punches modules. 


The SET command has operands that allow you to enter or 
leave the CMS/DOS environment (SET DOS ON or SET DOS 
OFF) to set the number of SYSLST lines per 

page (SET DOSLNCNT), to set the UPSI byte (SETUPSI), 
and to set a virtual partition size (SET DOSPART). 


Creates CMS COPY files from books on VSE/AF source 
statement libraries. 
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Figure 18. 


CMS/DOS Commands and CMS Commands with Special Operands 
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DL/I in the CMS/DOS Environment 


Batch DL/I programs can be written and _ tested in the CMS/DOS 
environment. This includes all programs written in COBOL, PL/I, and 
Assembler language. 


Data base description generation and program specification block 
generation can also be executed. However, the application control block 
generation must be submitted to a DOS virtual machine for execution. 
The data base recovery and reorganization utilities must also be 
executed in a DOS virtual machine. 


This support provides the ability to: 


e iInteractively code DL/I control blocks and application programs that 
contain imbedded DL/I calls. 


e Store and maintain macros used to generate DL/I control blocks, and 
programs created under CMS, in the CMS library. Production libraries 
are thus isolated from the test environment. 


e Modify and compile programs using the CMS/DOS text manipulation and 
EXEC facilities. 


e tLink-edit and execute batch DL/I programs either interactively or in 
CMSBATCH. Online DL/I application programs reguiring access to 
CICS/VS must be submitted to a DOS virtual machine for link-editing, 
cataloging, and execution. 


The following restrictions apply: 
e All the existing guidelines and restrictions that apply to VSAM data 
set creation, maintenance, and application program use apply to DL/I 


data sets. 


e The CMS/DOS restriction on writing to seguential files applies to 
SHSAM and HSAM. 


e To assemble a DBD or PSB under CMS/DOS, you must first copy the 


DBDGEN and PSBGEN macros from the DOS source statement library to a 
CMS MACLIB. 


For nore information about using DL/I in the CMS/DOS environment, see 
DL/I DOS/VS Data Base Administration, SH24-5011. 


Using DOS Files on DOS Disks 


You can have DOS disks attached to your virtual machine by a directory 
entry or you can link to a DOS disk with the LINK command. You can use 
the ACCESS command to assign a mode letter to the disk: 


access 155 b 
and the RELEASE command to release it: 

release b 
Except for VSAM disks, you cannot write on DOS disks, or update DOS 
files on them. You can, however, execute programs and CMS/DOS commands 


that read from these files, and you can use the LISTDS command to 
display the file-ids of files on a DOS disk; for example: 


178 IBM VM/SP CMS User's Guide 


listds b 


You can also verify the existence of a particular file. For example, if 
the file-id is NEW.TEST.DATA you can enter: 


listds new.test.data.b 


listds new test data b 


If the file-id of the DOS file you want to verify contains embedded 
blanks, for example NEW.TEST DATA, then you have to enter the LISTDS 
commands with a question mark: 

listds ? b 
CMS responds: 

ENTER DATA SET NAME: 
and you can enter the exact file-id: 

new.test data 


If the data set exists, you receive a response: 


FM DATA SET NAME 
B NEW.TEST DATA 


READING DOS FILES 


Under CMS/DOS, you can execute programs that read DOS sequential (SAM) 
files; you can also execute programs that read and write VSAM files. 
You cannot, however, execute programs to read direct (DAM) or indexed 
sequential (ISAM) DOS files. 


Complete information on uSing CMS to access and Ranipulate VSAM files 
is described in "Section 10. Using Access Method Services and VSAM In 
CMS and CMS/DOS." The discussion below lists the restrictions placed on 
reading SAM files. 


Restrictions on Reading DOS Disk Files in CM 


CMS cannot read DOS files that: 

e Have the input security indicator on. 

e Contain more than 16 user labels and/or data extents. (If the file 
has user labels, they occury the first extent; therefore the file 
must contain no more than 15 data extents.) 

e Are multivolume files. Multivclume files are read as single-volune 
files. End of volume is treated as end of file. There is no 
end-of-volume switching. 


e Have user labels. User labels in user-labeled files are bypassed. 
CMS does not support duplicate volume labels; you cannot access more 


than one volume with the same six-character label while you are using 
CMS/DOS. 
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CREATING CMS FILES FROM DOS LIBRARIES 


You can create CMS files from existing DOS files on DOS disks. CMS 
Simulates the DOS librarian functions DSERV, RSERV, SSERV, ESERV, and 
PSERV with commands of the same names; you can use these CMS/DOS 
commands to create CMS files from relocatable, source statement, or 
procedure libraries located either on the DOS system residence volume or 
in private libraries. The functions are fully described later in this 
section. 


Copying DOS Disk and Tape Data 


Files 


If you want to create CMS files from DOS files that are not cataloged in 
libraries or from DOS files on tape, you can use the MOVEFILE command. 
The MOVEFILE command allows you to copy a file from one device to 
another device of the same or a different type. Before issuing the 
MOVEFILE command, the input and the output files must be described to 
CMS with the FILEDEF command. 


The MOVEFILE and FILEDEF commands are described and examples are 
given of how to use them in "Section 8. Developing OS Program Under 
CMS." The procedures are the same for copying DOS files as for OS data 
sets. You must, however, keep the following in mind: 


e Since DOS files on DOS disks do not contain BLKSIZE, RECFM, or LRECL 
options, these options must be specified via the FILEDEF command; 
otherwise, defaults of BLOCKSIZE=32760 and RECFM=U are assigned. 
LRECL is not used for RECFM=U files. 


e If a DOS file-id does not follow OS naming conventions (that is, one- 
to eight-byte qualifiers with each qualifier separated by a period; 
up to 44 characters including periods), you must use the DSN ? 
operand of FILEDEF and the ? operand of LISTDS to enter the DOS 
file-id. 


Copying Modules from DOS Library or SYSIN Tapes 


You can create individual CMS files for DOS modules from a DOS library 
distribution tape or DOS SYSIN’ tape. Use the VMFDOS command. The 
VMFDOS command can create a CMS file for each DOS nodule that exists, 
and the CMS filename corresponds to the DOS module name. You can 
restore individual modules, groups of modules, or the entire module set. 


For DOS library distribution tapes, the VMFDOS command restores 
modules from either system or private (relocatable and/or source 
statement) libraries. The created CMS files have a filetype of 'TEXT* 
if they are from a relocatable library. They have a filetype of ‘MACRO! 
if they are from a source statement library. 


For DOS SYSIN tapes, modules containing a period as the second 
character (for example, 'A.') of a DOS ‘'CATALx' control statement have a 
filetype of "MACRO". All other files have a filetype of *TEXT'. 


The VMFDOS command is described in the VM/SP Planning and Systen 
Generation Guide. 
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Reading in Real Card Decks 


If you have DOS files or source programs on cards, you can create CMS 
files directly by having these cards read into the real system card 
reader. You direct the cards to your virtual machine by punching a CP 
ID card in this format; 


ID HARMONY 


and placing this card in front of your card deck. When the cards appear 
in your virtual card reader, you can read them onto your CMS A-disk with 
the READCARD command: 


readcard dataproc assemble 


You can use the editor to remove any DOS control cards that may be 
included in the deck. 


Using Tapes in CMS/DOS 


See "Tape Labels in CMS" for a description of CMS tape label processing 
for CMS/DOS tape files. The support for tape labels is only for files 
defined by a DTFMT macro. If you donot use this macro, CMS bypasses 
IBM standard labels on input tapes and writes a tape mark over any 
existing labels on an output tape. The CMS LABELDEF command is 
equivalent in CMS/DOS to the VSE/AF TLBL control statement when standard 
tape label processing is used. 


Using the ASSGN Command 


The ASSGN and DLBL commands perform the same functions for CMS/DOS as 
the ASSGN and DLBL control statements in VSE/AF. You use the ASSGN 
command to deSignate an I/O device for a system or programmer logical 
unit (SYSxxx) and, if the device is a disk device, you can use the DLBL 
command to establish a real file identification for a symbolic filename 
in a progran. The DLBL command is described under “Using the DLBL 
Command." 


In addition to using the ASSGN command to relate real I/0O devices 
with symbolic units, you must use it in CMS/DOS to: 


e Assign SYSIN or SYSIPT for the input source file for a language 
compiler when you use the DOSPLI or FCOBOL commands. 


e Identify the disk, by mode letter, on which a private core image, 
relocatable, or source statement library resides. 


e Assign SYSIN or SYSIPT to the CMS disk on which an ESERV file, 
containing control statements for the ESERV program, resides. 


When you enter the ASSGN command, you must supply the logical unit 
and the device; for example; 


assgn sys100 printer 
assigns the logical unit SYS100 to the printer. When you want to make 


an assignment to a disk device, you must specify the mode letter at 
which the disk is accessed. The ccmmand: 
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assgn sys010 b 
assigns the logical unit SYS010 to your B-disk. 


The system logical units you can assign and the valid device types 
you can assign to them in CMS/DOS follow. 


SYSIPT, SYSRDR, SYSIN: These units can be assigned to disk (mode), TAPE, 
or READER. If you make an assignment to SYSIN, both SYSRDR and SY¥SIPT 
are also assigned the same device. Assignment to DOS FB-512 disks is not 
supported. 


SYSLST: The system logical unit for listings can be assigned to disk 
(mode), PRINTER, or TAPE. 


SYSLOG: Terminal or operator output or messages can be assigned to 
PRINTER or TERMINAL. CMS/DOS always assigns SYSLOG to TERMINAL by 
default, so you never have to make this assignment except when you want 
to alter it. 


SYSPCH: Punched output, for example text decks, can be assigned to 
PUNCH, disk (mode), or TAPE. 


SYSCLB, SYSRLB, SYSSLB: The system logical units SYSCLB, SYSRLB, and 
SYSSLB can be assigned to private core image, relocatable, and source 
statement libraries, respectively. The only valid assignments for these 
units is to disk (mode). If you want to reference private libraries 
with the DOSLKED, DSERV, ESERV, FETCH, SSERV, or RSERV commands, you 


must assign SYSCLB, SYSRLB, or SYSSLB to the disks on which the 
libraries reside. 


MANIPULATING DEVICE ASSIGNMENTS 


You can assign programmer logical units SYS000 through SYS241 with the 
ASSIGN command. Besides assigning I/O devices, the ASSGN command can 
also negate a previous assignment: 

assgn syspch ua 


or specify that, for a given device, no real I/O operation is’ to be 
performed during the execution of a progran: 


assgn sys009 ign 


When you release a disk from your virtual machine, any assignments made 
to that disk are unassigned. 


You can find out the current assignments for system and programmer 
logical units with the LISTIO command, which lists all the system or 
programmer logical units, even those that are unassigned: 

listio 
To list only currently assigned units, enter: 
listio a 


To find out the current assignment of one specific unit, for example 
SYS100, enter: 


listio sys100 
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With the EXEC option of the LISTIO command, you can create a disk 
file containing the list of assignments. The $LISTIO EXEC that is 
created contains two EXEC numeric variables, 6&1 and 6&2, for each unit 
listed. For example, if you entered the command: 


listio sys081 (exec 
then the file $LISTIO EXEC may contain the record: 


&1 &2 SYSO081 PRINTER 


When you use the STAT option, LISTIO lists, for disk devices, whether 
the disk is read-only or read/write; for example: 


listio sys100 
SYS100 B R/W 


indicates that SYS100 is assigned to the B-disk, which is a read/write 
disk. 


You can cancel all current assignments by leaving the cCMS/DOS 
environment and then re-entering it: 


set dos off 
set dos on 


VIRTUAL MACHINE ASSIGNMENTS 


When you assign a physical device type to a-system or programmer logical 
unit, CMS relates the device to your virtual machine configuration; you 
receive an error message if you try to assign a logical unit to a device 
not in your configuration. For example, if you are using the ASSGN 
command to assign a logical unit to a disk file, you must specify the 
access mode letter of the disk. If the disk is not accessed, the ASSGN 
command fails. 


For another example, if you issue: 
assgn syspch punch 


the punch specified is your own virtual machine card punch. The actual 
destination of punched output then depends on the spooling 
characteristics of the punch; if it is spooled to another user or to *, 
then no real cards are punched, but virtual card images are placed in 
the virtual reader of the destination userid, which may be another 
virtual machine or your own. 


CMS supports only one reader, one punch, and one printer; you cannot 
make any asSignments for multiple output devices in CMS/DOS. When you 
make an assignment for a logical unit that has already been assigned, it 
replaces the current assignment. 


Using the DLBL Command 


Yse the DLBL command to supply CMS/DOS with specific file identification 
information for a disk file that is going to be used for input or 
output. For any DLBL command you issue, you must previously have issued 
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an ASSGN command for the disk, specifying a system or programmer logical 
unit. The basic relationship is: 


assgn SYSxxx mode 
dibl filename mode DSN ? (SYSxxx 


Both the SYSxxx and the mode values must match on the ASSGN and DLBL 
commands; the disk on which the file resides must be accessed at node. 


The filename on the DLBL command line, called a ddname in CMS/DOS, 
corresponds to the symbolic name for a file in a program. If you want to 
reference a private DOS library, you must use one of the following 
ddnames: 


systen 
Logical Unit Filename 
SYSCLB IJSYSCL 
SYSRLB IJSYSRL 
SYSSLB IJSYSSL 


ENTERING FILE IDENTIFICATIONS 


When you issue the DLBL command you must identify the file, by file-id 
(for a VSE file) or by file identifier (for a CMS file). The keywords 
DSN and CMS indicate whether it isa VSE file or a CMS file, 
respectively. 


If the file is a VSE file residing on a DOS disk, you can enter the 
DLBL command in one of three ways. For example, for a file named 
TEST.FILE.INPUT you may enter either: 


assgn sys101 d 
dlbl infile d dsn test.file.input (sys101 


dlbl infile d dsn test file input (sys101 


assgn sys101 d 
dlbl infile d dsn ? (sys101 


ENTER DATA SET NAME: 
test.file.input 


For any VSE file with a file-id that contains embedded blanks, you 
must use the "DSN ?" forn. 


When you issue a DLBL command for a CMS file, you enter the filename 
and filetype following the keyword CMS: 


assgn sys102 a 
dibl outfile a cms new output (sys102 


In this example, if SYS102 is defined as an output file for a progran, 
the output is written to your CMS A-disk in a file named NEW OUTPUT. 


You can, for convenience, use a CMS default file identifier. If you 
enters 


dlbl outfile a cms (sys102 
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then the output filetype defaults to that of the ddname and the filenane 
to FILE. So, this output file is named FILE OUTFILE. 


eat meme committer SS EE 


You can clear a DLBL definition for a file by using the CLEAR operand of 
the DLBL command: 


dibl outfile clear 


To clear all existing definitions, except those entered with the PERM 
option, you can enter: 


dlbl * clear 
This command is issued by the assembler and the language processors when 
they complete execution. Definitions entered with the PERM option must 
be individually cleared. 
Whenever you use the HX Immediate command to halt the execution of a 
program, the DLBL definitions in effect are cleared, including those 
entered with the PERM option. 


You can find out what definitions are currently in effect by issuing 
the DLBL command with no operands; 


d1lbl 


or, you can use the QUERY command with the DLBL operand. 


Using DOS Libraries in CMS/DOS 


CMS/DOS provides you with the capability of using various types of files 
from DOS system or private libraries. You can copy, punch, display at 
the terminal, or print: 


e Books from system or private source statement libraries using the 
SSERV command 


e Relocatable modules from system or private relocatable libraries 
using the RSERV command 


e Procedures from the system procedure library using the PSERV command 
You can also: 


e Copy and de-edit macros from system and private E sublibraries using 
the ESERV command 


e Access the directories of system or private libraries using the DSERV 
command 


e tLink-edit relocatable modules from system or private relocatable 
libraries with the DOSLKED command 


e Read core image phases from system or private core image libraries 
into storage for execution using the FETCH command 
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THE SSERV COMMAND 


If you have cataloged source programs or copy files on the system source 
statement library and you want to use CMS to modify and test them, you 
can copy them into CMS files using the SSERV command. For example, 
suppose you want to copy a book named PROCESS from the A sublibrary on 
the system residence volume. The DOS system residence is in your 
Virtual machine configuration at virtual address 350, and you have 
accessed it as your F-disk. First, to indicate to CMS/DOS’ that the 
system residence is on your F-disk, you enter: 


set dos on f 


then you can enter the SSERV command, specifying the sublibrary 
identification and the book name: 


sserv a process 


This creates, from the A sublibrary, a file named PROCESS COPY and 
places it on your A-disk. If the book contained assembler language 
source statements you would want the filetype to be ASSEMBLE, so you may 
enter: 


sserv a process assemble 


If you want to copy a book from a private source statement library, 
you must first use the ASSGN and DLBL commands to make the library known 
to CMS/DOS. For example, to obtain a copy file from a private library 
on a DOS disk accessed as your D-disk, enter: 


assgn sysslb d 

dlbl ijsyssl d dsn ? (sysslb 
ENTER DATA SET NAME: 
program.test library 


Now, when you enter the SSERV command: 
sserv t setup copy 


the book named SETUP in the Tf sublibrary of PROGRAM.TEST LIBRARY is 
copied into a CMS file named SETUP COPY. If SETUP is not found in the 
private library, then CMS searches the system library, if it is 
available. 


THE RSERV COMMAND 


In CMS/DOS, to manipulate relocatable modules that have been cataloged 
either on the system or a private relocatable library you must first 
copy them into CMS files with the RSERV command. You can link-edit 
modules directly from DOS relocatable libraries, but if you want to add 
or modify linkage editor control statements for a module, you must place 
the control statements in a CMS file. 


If you are copying a relocatable module from the system relocatable 
library, then you should make sure that you have indicated the systen 
residence disk when you entered the CMS/DOS environment: 

set dos on f 


then you can issue the RSERV command specifying the name of the 
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relocatable module you want to copy: 
rserv rtna 


The execution of this command results in the creation of a CMS file 
named RTNA TEXT on your A-disk. 


If you want to copy a relocatable module from a private relocatable 
library, you must first use the ASSGN and DIBL commands to amake the 
private library known to CMS/DOS: 


assgn sysrlb d 
dlbl ijsysrl d dsn reloc.lib (sysrlb 


Then, issue the RSERV command for a specific module in that library: 
rserv testrtna 


to create the CMS file TESTRINA TEXT from the module named TESTRINA. If 
the module TESTRTNA is not found in RELOC.LIB, CMS searches the systen 
library, if it is available. 


THE PSERV COMMAND 


If you want to copy DOS cataloged procedures into CMS files to use, for 
example, in preparing job streams for a DOS virtual machine, you can use 
the PSERV command: 


pserv prepjob 


This command creates a CMS file on your A-disk; the file is named 
PREPJOB PROC. To copy a procedure from the procedure library you must 
have entered the CMS/DOS environment specifying a disk mode for the 
system residence volume. 


You cannot execute DOS/VS procedures directly from the CMS/DOS 
environment. However, if you modify a procedure, you can punch it toa 
virtual machine that is running a DOS system, and execute it there. 


THE ESERV COMMAND 


The CMS/DOS ESERV command is actually an EXEC procedure that calls 
the VSE/AF ESERV utility program. To use the ESERV program, you first 
must IPL CMS with a CMSBAM DCSS (shared segment), then create a file 
with a filetype of ESERV that contains the ESERV control statements you 
want to execute. For example, if you want to write a de-edited copy of 
the macro DTFCD onto your A-disk, you might create a file named DTFCD 
ESERV, with the record: 


PUNCH £E.DTFCD 
As when you submit ESERV jobs in DOS column 1 must be blank. 
Prior to executing the ESERV program, you must enter the CMS/DOS 
environment by specifying the SET DOS ON command using a VSE/AF systen 


residence volume. This is necessary because the ESERVE procedure 
invokes the ESERV program directly from the VSE/AF core image library. 
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Then, you must assign SYSIN to the device on which the ESERV source 
file resides, usually your A-disk: 


assgn sysin a 


Then you can enter the ESERV command specifying the filename of the 
ESERV file: 


eserv dtfcd 


No other ASSGN commands are required; the CMS/DOS ESERV EXEC makes 
default assignments for SYSPCH and SYSLST to disk. 


To copy and de-edit macros from a private E sublibrary, issue the 
ASSGN and DLBL commands to identify the library. For example, to 
identify a source statement library named TEST.MACROS on the DOS disk 
accessed as the C-disk, enter: 


assgn sysslbc 
dlbl ijsyssl c dsn test.macros (sysslb 


The SYSLST output is contained in a CMS file with the same filenane 
as the ESERV file and a filetype of LISTING; you must examine the 
LISTING file to see if the ESERV program executed successfully. You can 
either edit it, or display its contents with the TYPE command: 


type dtfcd listing 


The SYSPCH output is contained ina file with the same name as the 
ESERV file and a filetype of MACRO. If you want to punch ESERV output 
to your virtual card punch, make an assignment of SYSPCH to PUNCH. 


When you use the PUNCH or ODSPCH ESERV control statements, CATAL.S, 
END, or /* records may be inserted in the output file. When you use the 
MACLIB command to add the MACRO file to acCMS macro library, these 
statements are ignored. 


See "Jsing Macro Libraries" for information on creating and 
Banipulating CMS macro libraries. 


THE DSERVY COMMAND 


You can use the DSERV command to examine the contents of system or 
private libraries. If you do not specify any options with it, the DSERV 
command creates a disk file, named DSERV MAP, on your A-disk. You can 
use the PRINT or TERM options to specify that the directory list is 
either to be printed on your spooled printer or displayed at your 
terminal. You can also use the SORT option to create a list in 
collating sequence. 


In order to examine a system directory, you must have entered the 
CMS/DOS environment specifying the mode letter of the DOS’ systen 
residence: 


set dos on f 


If you want to examine the directory of a private source statement, 
core image, or relocatable library you must issue the ASSGN and DLBL 
commands establishing SYSSLB, SYSCLB, or SYSRLB before using the DSERV 
command. 
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For example, to display at your terminal an alphameric list of 
procedures cataloged on the system procedure library, you would issue: 


dserv pd (sort tern 


If the directory you are examining is for a core image library, you 
can specify a particular phase name to ascertain the existence of the 
phase: 


dserv cd phase $$bopen (tern 


To list the directory of a private source statement library, you 
would first issue the ASSGN and DLBL commands: 


assgn sysslb b 
dlbl ijsyssl b dsn test.source (sysslb 


then enter the DSERV command: 
dserv sd 


The CMS file, DSERV MAP A, that is created in this example contains the 
directory of the private source statement library TEST.SOURCE. 


USING DOS CORE IMAGE LIBRARIES 


You can load core image phases from DOS core image libraries into 
virtual storage and execute them under CMS/DOS. Since CMS cannot write 
directly to DOS disks, linkage editor output under CMS/DOS is placed in 
a special C¥%S file called a DOSLIB. When you execute the FETCH command 
in CMS/DOS you can load phases from either system or private DOS core 
image libraries as well as from CMS DOSLIBs. More information on using 
the FETCH command is contained under "Executing Programs in CMS/DOS." 


Using Macro Libraries 


DOS macro libraries cannot be accessed directly by the VM/SP assembler. 
If you want to assemble DOS programs in CMS/DOS that use DOS macro or 
copy files that are on the system or a private macro library you nust 
first create a CMS macro library (MACLIB) containing the macros you wish 
to use. Since the process of creating a CMS MACLIB from the DOS systen 
source statement library (E sublibrary) can be very time-consuming, you 
should check with your installation's system programmer to see if it has 
already been done, and to verify the filename of the macro library, so 
that you can use it in CMS/DOS. 


Note: The DOS, PL/I and DOS/VS COBOL compilers executing in CMS/DOS 
cannot read macro or copy files from CMS MACLIBsS. Macros and copy files 
are obtained instead from a DOS source statement library. 


If you want to extract DOS system macros to modify them for your 


private use, or if you want to use macros from a private library in CMS, 
you must use the procedure outlined below to create the MACLIB files. 
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CMS MACLIBS 


A CMS macro library has a filetype of MACLIB. You can create a MACLIB 
from files with filetypes of MACRO or COPY. A MACRO file may contain 
macro definitions; COPY files contain predefined source statements. 


When you want to assemble a source program that uses macro or copy 
definitions, you must ensure that the library containing the code is 
identified before you invoke the assembler. Otherwise, the library is 
not searched. You identify libraries to be searched using the GLOBAL 
command. For example, if you have two MACLIBs that contain your private 
wacros and copy files whose names are TESTMAC MACLIB and TESTCOPY 
MACLIB, you would issue the command: 


global maclib testmac testcopy 


The libraries you specify on a GLOBAL command line are searched in the 
order you specify then. A GLOBAL command remains in effect for the 
remainder of your terminal session, or until you IPL CMS. To find out 
what macro libraries are currently available for searching, issue the 
command: 


query maclib 


You can reset the libraries or the search order by reissuing the GLOBAL 
command. 


CREATING A CMS MACLIB 


To create a CMS macro library, each macro or copy file you want included 
in the MACLIB must first be contained in a CMS file with a filetype of 
COPY or MACRO. If you are creating a CMS MACLIB file from a DOS library 
you must use the SSERV command to copy a file from any source statement 
library other than an E sublibrary, or use the ESERV command to copy and 
de-edit a macro from an E sublibrary. The SSERV command uses a default 
filetype of COPY; the ESERV command uses a default filetype of MACRO. 


The following example shows how to copy macros from various sources 
and shows how to create and use the CMS MACLIB that contains’ these 
macros. 


1. Enter the CMS/DOS environment with the DOS system residence ona 
disk accessed as mode C: 


set dos onc 


2. Copy the macro book named OPEN from the A sublibrary of the systen 
source statement library: 


sserv a open 
3. Establish a private source statement library: 
access 351 d 
assgn sysslb d 
dlbl ijsyssl d dsn ? (sysslb 
test source. lib 


4. Issue the SSERV command for a macro in the M sublibrary of TEST 
SOURCE.LIB: 
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sserv m releas 
5. Create an ESERV file to copy from the E sublibrary: 
edit contrl eserv 
NEW FILE 
EDIT: 
input punch contrl 
file 
6. Execute the ESERV command: 


assgn sysin a 
eserv contrl 


7. (Create acCMS macro library named MYDOSMAC from the files just 
created, which are named OPEN COPY, RELEAS COPY, and CONTRL MACRO: 


maclib gen mydosmac open releas contrl 
8. To use these macros in an assembler language program, you must 
indicate that this MACLIB is accessible before assembling a source 
file: 


global maclib nydosmac 


THE MACLIB COMMAND 


The MACLIB command performs a variety of functions. You use it to: 


Create the MACLIB (GEN function) 

Add, delete, or replace members (ADD, DEL, and REP functions) 
Compress the MACLIB (COMP function) 

List the contents of the MACLIB (MAP function) 


Descriptions of these MACLIB command functions follow. 
GEN Function: The GEN (generate) function creates a CMS macro library 
from input files specified on the command line. The input files must 
have filetypes of either MACRO or COPY. For example: 

Maclib gen mymac get pdump put regegu 


creates a macro library with the file identifier MYMAC MACLIB A1 from 
macros existing in the files with the file identifiers: 


GET |{MACRO|,PDUMP {MACRO|, PUT {MACRO),and REGEQU jJMACRO 
COPY COPY COPY COPY 


If a file named MYMAC MACLIE A1 already exists, it is erased. 


Assume that the files GET MACRO, PDUMP COPY, PUT MACRO, and REGEQU 
COPY exist and contain macros in the following forn: 


GET MACRO PDUMP COPY PUT MACRO REGEQU COPY 
GET *COPY PDUMP PUT XREG 
PDUMP 
WAIT *COPY WAIT YREG 
WAIT 
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The resulting file, MYMAC MACLIB Al, contains the members: 


GET WAIT 
WAIT PUT 
PDUMP REGEQU 


The WAIT macro, which appears twice in the input to the command, also 
appears twice in the output. The MACLIB command does not check for 
duplicate macro names. If, at a later time, the WAIT macro is requested 
from MYMAC MACLIB, the first WAIT macro encountered in the directory is 
used. 


When COPY files are added to MACLIBs, the name of the library member 
is taken from the name of the COPY file, or from the *COPY statement, as 
in the file PDUMP COPY, above. Note that although the file REGEQU COPY 
contained two macros, they were both included in the MACLIB with the 
Name REGEQU. When the input file is a MACRO file, the member name is 
taken from the macro prototype statement in the MACRO file. 


ADD Function: The ADD function appends new members to an existing macro 
library. For example, assume that MYMAC MACLIB A1 exists as created in 
the example in the explanation of the GEN function and the file DTFDI 
COPY exists as follows: 


*COPY DTFDI 
DTFDI macro definition 
*COPY DIMOD 
DIMOD macro definition 
If you issue the command: 
maclib add mymac dtfdi 


the resulting MYMAC MACLIB A1 contains the members: 


GET PUT 

WAIT REGEQU 
PDUMP DTFDI 
WAIT DIMOD 


REP Function: The REP (replace) function deletes the directory entry for 
the macro definition in the files specified. It then appends new macro 
definitions to the macro library and creates new directory entries. For 
example, assume that a macro library TESTMAC MACLIB contains the members 
A, B, and C, and that the following command is entered: 


maclib rep testmac ac 


The files represented by file identifiers A MACRO and C MACRO each have 
one macro definition. After execution of the command, TESTMAC MACLIB 
contains members with the same names as’ before, but the contents of A 
and C are different. 


DEL Function: The DEL (delete) function removes the specified macro name 
from the macro library directory and compresses the directory so there 
are no unused entries. The macro definition still occupies space in the 
library, but since no directory entry exists, it cannot be accessed or 
retrieved. If you attempt to delete a macro for which two macro 
definitions exist in the macro library, only the first one encountered 
is deleted. For example: 


Maclib del mymac get put wait dtfdi 
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deletes macro names GET, PUT, WAIT, and DTFDI from the directory of the 
macro library named MYMAC MACLIB. Assume that MYMAC exists as in the ADD 
function example. After the above command, MYMAC MACLIB' contains the 
following members: 


PDUMP 
WAIT 
REGEQU 
DIMOD 


COMP Function: Execution of a MACLIB command with the DEL or REP 
functions can leave unused space within a macro library. The COMP 
(compress) function removes any macros that do not have directory 
entries. This function uses a temporary file named MACLIB CMSUT1. For 
example, the command: 


Maclib comp mymac 
compresses the library MYMAC MACLIB. 


MAP Function: The MAP function creates a list containing the name of 
each macro in the directory, the size of the macro, and its position 
within the macro library. If you want to display a list of the members 
of a MACLIB at the terminal, enter the command: 


Maclib map mymac (term 


The default option, DISK, creates a file on your A-disk which has a 
filetype of MAP and a filename equal to the filename of the MACLIB. If 
you specify the PRINT option, then a copy of the map file is spooled to 
your virtual printer as well as being written onto disk. 


Manipulating MACLIB Members 


The following CMS commands supply a MEMBER option, which allows you to 
reference individual members of a MACLIB: 


PRINT (to print a member) 

PUNCH (to punch a member) 

TYPE (to display a member) 

FILEDEF (to establish a file definition for a member) 


You can use the CMS editor to create the MACRO and COPY files and 
then use the MACLIB command to place them ina library. Once they are 
in a library, you can erase the original files. 

To extract a member froma macro library, you can use either the 
PUNCH or the MOVEFILE command. If you use the PUNCH command you can 
spool your virtual card punch to your own virtual reader: 

cp spool punch to * 
Then punch the member; 
punch testmac maclib (member get noheader 


and read it back onto disk: 


readcard get macro 


Section 9. Developing DOS Programs under CMS 193 


In the above example, the member was punched with the NOHEADER option of 
the PUNCH command, so that a name could be assigned on the READCARD 
command line. If a header had been created for the file, it would have 
indicated the filename and filetype as GET MEMBER. 


If you use the MOVEFILE command, you must issue a file definition for 
the input member name and the output macro or copy file before entering 
the MOVEFILE command: 


filedef inmove disk testcopy maclib (member enter 
filedef outmove disk enter copy a 
movefile 


This example copies the member ENTER from the macro library TESTCOPY 
MACLIB A into a CMS file named ENTER COPY. 


When you use the PUNCH or MOVEFILE commands to extract members fron 
CMS MACLIBs, each member is followed by a // record, which is a MACLIB 
delimiter. You can edit the file and use the DELETE subcommand to 
delete the // record. 


If you wish to move the complete MACLIB to another file, use the 
COPYFILE command. 


system MACLIBs 


The macro libraries that are on the system disk contain CMS, DOS, and OS 
assembler language macros. The MACLIBS ares: 


e CMSLIB MACLIB, which contains the CMS macros. 


e DMSSP MACLIB, which contains CMS macros for VM/SP (Program No. 
5664-167) . 


e OSMACRO MACLIB, OSMACRO1 MACLIB, and TSOMAC MACLIB, which are used by 
OS programmers. 


DOS Assembler Language Macros Supported 


Figure 19 lists the VSE/AF assembler language macros supported by 
CMS/DOS. You can assemble source programs that contain these macros 
under CMS/DOS, provided that you have the macros available in either 
your own or a shared CMS macro library. The macros whose functions are 
described in the "Function" column with the term "no-op" are supported 
for assembly only; when you execute programs that contain these macros, 
the VSE/AF functions are not performed. To accomplish the macro 
function you must execute the program in a VSE/AF virtual machine. 
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ee ae 


| Macro: jsvc | Function | 
| l [ | 
| CALL | —- | Pass control to another program | 
| CANCEL | 06 | =Terminate processing | 
| CDLOAD 1 55 | Load a VSAM phase | 
| CHECK | - | Verify completion of a read or write operation | 
| CLOSE/ [= I l 
| CLOSER | — | Deactivate a data file | 
| CNTRL | - | Control a physical device | 
| COMRG | 33 | #=Peturn address of background partition | 
| | - | communication region | 
{ DEC | 41 | no—op | 
| DTPxx! | - | Establish file definitions | 
| DUMP | - | Dump storage and registers and terminate processing | 
1 ENO | 42 | nho—op | 
| EOJ 114 | £=Terminate processing normally | 
| E°ET !- 1 Provide an error routine | 
| ExCP { 00 | £=Execute a channel program | 
{| EXIT PC | 17 | Return €rom program check routine | 
| FXIT AB | 95 | Return from abnormal termination routine | 
| EXTRACT | 98 | £=Retrieve PUB, storage boundaries, or CPUID | 
| | | information | 
| FCEPGOUT | 86 | #£=No-op ! 
| FETCH | 01 | Load and pass control to a phase | 
| 1 092 | Load and pass control to a logical transient | 
| FREE | 36 | no-op | 
| FREEVIS | 62 | Release user free storage | 
| GENL | - | Generate a phase directory list | 
| GET | - | Access a sequential file | 
| GETVIS | 61 | £=Obtain user free storage | 
| GETIMF | 34 | Get the time of day | 
| JDUMP | - | Dump storage and registers and terminate processing | 
| LOAD | 0&4 | Read a phaSe into storage | 
| LOCK/ | | l 
| UNLOCK |119 | Resource control | 
| MVCOM | 05 | Modify bytes in the partition communication region | 
| NOTE | - | Manage data set access | 
| OPEN/ = I | 
| OPENR | — | Activate a data file | 
| PAGEIN | 87 | no-op 
| PDIMP | - | Dump storage and registers and continue processing | 
| PFIX | 67 | no-op | 
| PFREE { 68 | no-op | 
| POINTR | - | Position a file for reading | 
| POINTS | - | Reposition a file to its beginning | 
| POINT™W | - | Position a file for writing | 
| POST |} 40 | #£=Post the event control block | 
| PRTOV | - | Control printer overflow | 
| PUT | - | Write to a sequential file | 
| PUTR | - | Communicate with the system operator | 
| FEAD | - | Access a sequential file | 
| RELPAG {| 85 | no-op | 
| RELSE | - | Skip to begin reading next block | 
| RETURN | - | Return control to calling progran | 
| RUNMODE | 66 | Check if program is running real or virtual | 
| SECTVAL | 75 | Obtain a sector number | 
| SETINE }10/24| no—-op | 
] SETPFA |} 71 |] #4=no-op | 
| STXIT AB | 37 {| =Provide or terminate linkage to abnormal ending | 
| PC | 16 | routine | 
| IT | 20 | no—op | 
| oc | 18 | no—op | 
| SUBSID {105 | Retrieve information on supervisor subsysten | 
| TROUNC | - | Skip to begin writing next block | 
| TTIMER | 52 | =Peturn a 0 in Register 0 (effectively a noop) | 
| WAIT {| OF | =Wait for the completion of I/0 | 
| WRITE | - | Write to a sequential file | 
| xxMOD2 | - | Create Logical IOCS routine inline | 
|-___-_—_-_— l 
| !1The declarative macros supported are: | 
| DTFCN, D™FCD, DTFPR, DTFDI, DIFST, DTFSD | 
| [ 
| #The DOS logic modules supported are: | 
| CDMOD, PRMOD, DIMOD, MTMOD | 
ac a eS a ere 


Figure 19. VSE/AF Macros Supported by CMS 
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Assembling Source Programs 


If you are a DOS assembler language programmer using CMS/DOS, you should 
be aware that the assembler used is the VM/SP assembler, not’ the DOS 
assembler. The major difference is that the VM/SP assembler, invoked by 
the ASSEMBLE command, is designed for interactive use, so that when you 
assemble a program, error messages are displayed at your terminal when 
compilation is completed, and you do not have to wait for a printed 
listing to see the results. You can correct your source file and 
reassemble it immediately. When your program assembles without errors, 
you can print the listing. 


To specify options to be used during the assembly, you enter them on 
the ASSEMBLE command line. So, for example, if you do not want the 
output LISTING file placed on disk, you can direct it to the printer: 


assemble nyfile (print 


All of the ASSEMBLE command options are listed in VM/SP CMS Command and 
Macro Reference. 


When you invoke the ASSEMBLE command specifying a file with a 
filetype of ASSEMBLE, CMS searches all of your accessed disks, using the 
standard search order, until it locates the file. When the assembler 
creates the output LISTING and TEXT files, it writes them onto disk 
according to the following priorities: 


1. If the source file is on a read/write disk, the TEXT and LISTING 
files are written onto the same disk. 


2. If the source file iS on a read-only disk that is an extension of a 
read/write disk, the TEXT and LISTING files are written onto the 
parent disk. 


3. If the source is on any other read-only disk, the TEXT and LISTING 
files are written onto the A-disk. 


In all of the above cases, the filenames assigned to the TEXT and 
LISTING files are the same as the filename of the input file. 


The output files used by the assembler are defined via FILEDEF 
commands issued by CMS when it calls’ the assembler. If you issue a 
FILEDEF command using one of the assembler ddnames before you issue the 
ASSEMBLE command, you can override the default file definitions. 


The ddname for the source input file is ASSEMBLE. If you enter: 


filedef assemble reader 
assemble sample 


then the assembler reads your input file from your card reader, and 
assigns the filename SAMPLE to the output TEXT and LISTING files. You 
can use this method to assemble programs directly from DOS sequential 
files on DOS disks. For example, to assemble a source file naned 
DOSPROG from a DOS disk accessed as a C-disk, you could enter: 


filedef assemble c dsn dosprog (recfm f lrecl 80 
assemble dosprog 


Again, the name you assign on the ASSEMBLE command may be anything; the 
assembler uses this name to assign filenames to the TEXT and LISTING 
output files. 


LISTING and TEXT are the ddnames assigned to the SYSLST and SYSPCH 
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output of the assembler. You might issue file definitions to override 
these defaults as follows: 


filedef listing disk assemble listfile a 
filedef text disk assemble textfile a 
assemble source 


When these commands are executed, the output from the assembly of the 
file SOURCE ASSEMBLE is written to the disk files ASSEMBLE LISTFILE and 
ASSEMBLE TEXTFILE. 


Link-editing Programs in CMS/DOS 


When the assembler or one of the language compilers executes, the object 
module produced is written to a CMS disk ina file with a filetype of 
TEXT. The filename is always the same as that of the input source file. 
These TEXT files (sometimes referred to as decks, although they are not 
real card decks) can be used as input to the linkage editor or can be 
the target of an INCLUDE linkage editor control statement. 


You can invoke the CMS/DOS linkage editor with the DOSLKED command, 
for example: 


doslked test testlib 


where TEST is the filename of either a DOSLNK or TEXT file (that is, a 
file with a filetype of either DOSLNK or TEXT) or the name of a 
relocatable module in a system or private relocatable library. .TESTLIB 
indicates the name of the output file which, in CMS/DOS, is a phase 
library with a filetype of DOSLIB. 


When you issue the DOSLKED command, CMS first searches for a file 
with the specified name and a filetype of DOSLNK. If none are found, it 
searches the private relocatable library, if you have assigned one (you 
must issue an ASSGN command for SYSRLB and use the ddname IJSSYRL in a 
DLBL statement). If the module is still not found, CMS searches all of 
your accessed disks for a file with the specified name and a filetype of 
TEXT. Last, CMS searches the system relocatable library, if it is 
available (you must enter the CMS/DOS environment specifying the mode 
letter of the DOS system residence if you want to access’ the systen 
libraries). 


LINKAGE EDITOR INPUT 
You can place the linkage editor control statements ACTION, PHASE, 
INCLUDE, and ENTRY ina CMS file with a filetype of DOSLNK. When you 
use the INCLUDE statement, you may specify the filename of a CMS TEXT 
file or the name of a module in a DOS relocatable library: 

INCLUDE XYZ 


or you may use the INCLUDE control statement to indicate that the object 
code follows: 


INCLUDE 
(CMS TEXT file) 


A typical DOSLNK file, named CONTROL DOSLNK, might contain the 
following: 
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ACTION REL 

PHASE PROGMAIN,S 
INCLUDE SUBA 
PHASE PROGA,* 
INCLUDE SUBB 


When you issue the command: 
doslked control 


the linkage editor searches the following for the object files SUBA and 
SUBB: 


e A DOS private relocatable library, provided you have issued the ASSGN 
and DLBL commands to identify it: 


assgn sysrlb d 
dlbl ijsysrl d dsn ? (sysrlb 


e Your CMS disks for files with filenames SUBA and SUBB and a filetype 
of TEXT 


e The system relocatable library located on the DOS’ system residence 
volume (if it is available) 


Link-editing TEXT Files 


When you want to link-edit individual CMS TEXT files, you can insert 
linkage editor control statements in the file using the CMS editor and 
then issue the DOSLKED command; 


edit rtnb text 

EDIT: 

input include rtnec 
file 

doslked rtnb mydoslib 


When the above DOSLKED command is executed, the CMS file RTINB TEXT is 
used as linkage editor input, as long as there is no file named RINB 
DOSLNK. The ACTION statement, however, is not recognized in TEXT files. 


You can also link-edit relocatable modules directly from a DOS systen 
or private relocatable library, provided that you have identified the 
library. If you do this, however, you cannot provide control statements 
for the linkage editor. 


To link-edit a relocatable module from a DOS private library and add 
linkage editor control statements to it, you could use this procedure: 


1. Identify the library and use the RSERV command to copy the 
relocatable module into a CMS TEXT file. In this example, the 
module RTNC is to be copied from the library OBJ.MODS: 


assgn sysrlb e 
dlbl ijsysrl e dsn obj mods (sysrlb 
rserv rtnc 


2. Create a DOSLNK file, insert the linkage editor control statements, 
and copy the TEXT file created in step 1 into it using the GETFILE 
subcommand: 
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edit rtnc doslnk 


input action rel 
getfile rtnc text a 
file 


3. Invoke the linkage editor with the DOSLKED command: 
doslked rtnc mydoslib 


Alternatively, you could create a DOSLNK file with the following 
records: 


ACTION REL 
INCLUDE RTNC 


and link-edit the module directly from the relocatable library. If you 
do not need a copy of the module on a CMS disk, you might want to use 
this method to conserve disk space. 


When the linkage editor is reading modules, it may encounter a blank 
card at the end of a file, or a * (comment) card at the beginning of a 
file. In either case, it issues a warning message indicating an invalid 
card, but continues to complete the link-edit. 


LINKAGE EDITOR OUTPUT: CMS DOSLIBS 


The CHS/DOS linkage editor always places the link-edited executable 
phase ina CMS library with a filetype of DOSLIB. You should specify 
the filename of the DOSLIB when you enter the DOSLKED command: 


doslked prog0 templib 


where PROGO is the relocatakle module you are link-editing and TEMPLIB 
is the filename of the DOSLIB. 


If you do not specify the name of a DOSLIB, the output is placed ina 
DOSLIB that has the same name as the DOSLNK or TEXT file being 
link-edited. In the above example, a CMS DOSLIB is created naned 
TEMPLIB DOSLIB, or, if the file TEMPLIB DOSLIB already exists, the phase 
PROGO is added to it. 


DOSLIBS can contain relocatable core image phases suitable for 
execution in CMS/DOS. Before you can access phases in it, you must 
identify it to CMS with the GLOBAL command: 


global doslib templib permlib 


When CMS is searching for executable phases, it searches all DOSLIBs 
specified on the last GLOBAL DOSLIEF command line. If you have named a 
humber of DOSLIBs, or if any particular DOSLIB is very large, the time 
required for CMS to fetch and execute the phase increases. You should 
use separate DOSLIBs for executable phases, whenever possible, and then 
specify only the DOSLIBS you need on the GLOBAL command. 


When you link-edit a module into a DOSLIB that already contains a 
phase with the same name, the directory entry is updated to point to the 
hew phase. However, the space that was occupied by the old phase is not 
reclaimed. You should periodically issue the command: 


doslib comp libname 
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where libname is the filename of the DOSLIB, to compress the DOSLIB and 
delete unused space. 


Linkage Editor Maps 


The DOSLKED command also produces a linkage editor nmap, which it writes 
into a CMS file with a filename that is that of the name specified on 
the DOSLKED command line anda filetype of MAP. The filemode is always 
AS. If you do not want a linkage editor map, use the NOMAP option on 
the ACTION statement in a DOSLNK file. 


Executing Programs in CMS/DOS 


After you have assembled or compiled a source program and link-edited 
the TEXT files, you can execute the phases in your CMS virtual machine. 
You may not, however, be able to execute all your DOS programs directly 
in CMS. There are a number of execution-time restrictions placed on your 
virtual machine by VM/SP. You cannot execute a program that uses: 


Multitasking 

More than one partition 

Teleprocessing 

ISAM macros to read or write files 

CMS module files created by DOS programs 
Sets the EC mode bit in the PSW 


The above is only a partial list, representing those restrictions with 
which you might be concerned. For a complete list of restrictions, see 
the VWM/SP Planning and System Generation Guide. See also the usage 


EE —-_ S MMS SS CS (Pa: 


EXECUTING DOS PHASES 
You can load executable phases into your CMS virtual machine uSing the 
FETCH command. Phases must be link-edited before you load them; they 


must have been link-edited with ACTION REL. When you issue the FETCH 
command, you specify the name of the phase to be loaded: 


fetch myprog 
Then you can begin executing the program by issuing the START command: 
start 


Or, you can fetch a phase and begin executing it ona single command 
line: 


fetch prog2 (start 


When you use the FETCH command without the START option, CMS issues a 
message telling you at what virtual storage address the phase is loaded: 


PHASE PROG2 ENTRY POINT AT LOCATION 020000 
Location X'20000' is the starting address of the user program area for 
CMS; relocatable phases are always loaded starting at this address 


unless you specify a different address using the ORIGIN option of the 
FETCH command: 
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fetch prog3 (origin 22000 
start 


The program PROG3 executes beginning at location 22000 in the CMS user 
program area. 


SEARCH ORDER FOR EXECUTABLE PHASES 
When you execute the FETCH command, CMS searches for the phase name you 
specify in the following places: 
1. In a DOS private core image library on a DOS disk. If you have a 
private library you want searched for phases, you must identify it 


using the ASSGN and DLBL commands, using the logical unit SYSCLB: 


assgn sysclb d 
dlbl ijsyscl d dsn ? (sysclb 


2. In CMS DOSLIBsS on CMS disks. If you want DOSLIBS searched for 
phases, you must use the GLOBAL command to identify them to 
CMS/DOS: 

global doslib templib mylib 
You can specify up to eight DOSLIBs on the GLOBAL command line. 

3. On the DOS system residence core image library. If you want the 
system core image library searched you must have entered the 
CHS/DOS environment specifying the mode letter of the system 
residence: 

set dos on Zz 
When you want to fetch a core image phase that has copies in both the 

core image library and a DOSLIB, and you want to fetch the copy from the 
CMS DOSLIB, you can bypass the core image library by entering the 
command: 

assgn sysclb ua 
When you need to use the core image library, enter: 

assgn sysclb c 


where C is the mode letter of the system residence volume. You do not 
need to reissue the DLBL command to identify the library. 


MAKING I/O DEVICE ASSIGNMENTS 


If you are executing a program that performs I/0, you can use the ASSGN 
command to relate a system or programmer logical unit toa real I/0 
device: 


assgn syslst printer 
assgn sys052 reader 


In this example, your program is going to read input data from your 
Virtual card reader; the output print file is directed to your virtual 
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printer. If you want to reassign these units to different devices, you 
must be sure that the files have been defined as device independent. 


If you assign a logical unit to a disk, you should identify the file 
by using the DLBL command. On the DLBL command, you must always relate 
the DLBL to the system or programmer logical unit previously specified 
in an ASSGN command: 


assgn sys015 b 
dlbl myfile b dsn ? (sys015 


When you enter the DLBL command with the ? operand you are prompted to 
enter the DOS file-id. 


You must issue all of the ASSGN and DLBL commands necessary for your 
program's I/O before you issue the FETCH command to load the progras 
phase and begin executing. 


SPECIFYING A VIRTUAL PARTITION SIZE 


For most of the programs that you execute in CMS, you do not’ need to 
specify how large a partition you want those programs to execute in. 
When you issue the START command or use the START option on the FETCH 
command, CMS calculates how much storage is available in your virtual 
machine and sets a partition size. CMS calculates how much storage is 
available in the following manner: 


FREELOWE ~ (MAINHIGH + (4096 * FRERESPG) ) 

where; 

FREELOWE equals the low extent of allocated storage obtained from the 
top of virtual storage downwards via the DMSFREE systen 
request. 

MAINHIGH equals the high extent of allocated storage obtained from the 
low virtual storage upwards via the GETMAIN user request for 
storage. 


FRERESPG equals the amount of storage to be reserved for subsequent 
system requests, in pages. 


In some instances, you may want to control the partition size: 

°e For performance considerations 

e Because the default may not leave enough free storage to satisfy the 
GETVIS commands issued by the DOS program or the access’ method 


services function being executed. 


You can set the partition size with the DOSPART operand of the SET 
command. For example, after you enter the command: 


set dospart 300k 


all programs that you subsequently execute during this session will 
execute in a 300K partition. In this way you can: 


e Set a smaller partition size for programs that run better in smaller 
partitions. 
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e Set a smaller partition size to leave more free storage. If the 
reduction of the DOS partition does not free enough storage for the 
GETVIS commands, a larger virtual machine must be defined. 


If you enter: 
set dospart off 


the CMS calculates a partition size when you execute a program. This is 
the default setting. Note that the CMS partition, unlike the DOS 
partition, is used only for the loading and executing of programs 
invoked by the FETCH or LOAD commands. Areas allocated by GETVIS will 
be assigned addresses outside the partition but within the user's 
virtual machine. 


SETTING THE UPSI BYTE 


If your program uses the user program switch indicator (UPSI) byte, you 
can set it by using the UPSI operand of the CMS SET command. The UPSI 
byte is initially binary zeros. To set it to 1s, enter 


set upsi 11111111 
To reset it to zeros, enter: 


set upsi off 


Any value you set remains in effect for the duration of your terminal 
session, unless you reload CHS (with the IPL command). 


DEBUGGING PROGRAAS IN CMS/DOS 


You can debug your DOS programs in CMS/DOS using the facilities of CP 
and CMS. By execaeting your programs interactively, you can more quickly 
determine the cause of an error or program abend, correct it, and 
attempt to execute a program again. 


The CP and CMS debugging facilities are described in "Section 11. How 
VM/SP Can Help You Debug Your Programs." Additional information for 
assembler language programmers is in "Section 13. Programming for the 
CMS Environment." 


USING CMS EXEC PROCEDURES IN CMNS/DOS 


During your program development and testing cycle, you may want to 
create CMS EXEC procedures to contain sequences of CMS commands that you 
execute frequently. For example, if you need a number of MSACLIBs, 
DOSLIBs, and DLBL definitions to execute a particular program, you might 
have an EXEC procedure as follows: 
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S&CONTROL ERROR TIME 

SERROR &SEXIT GSRETCODE 

GLOBAL MACLIB TESTLIB DOSMAC 
ASSEMBLE TESTA 

PRINT TESTA LISTING 

DOSLKED TESTA TESTLIB 

GLOBAL DOSLIB TESTLIB PROGLIB 
ACCESS 200 E 

ASSGN SYS010 E 

&BEGSTACK 

DOS.TEST3.STREAM.BETA 

SEND 

DLBL DISK1 E DSN ? (S¥YS010 

ASSGN SYSO011 PUNCH 

CP SPOOL PUNCH TO * 

ASSGN SYS012 A 
DLBL OUTFILE A CMS TEST DATA (SYS012 
FETCH TESTA (START 

SIF GRETCODE = 100 &GOTO -RET100 
SIF GRETCODE = 200 &GOTO ~-RET200 
SEXIT S&RETCODE 

-RET100 SCONTINUE 


-RET200 SCONTINUE 


The SCONTROL and &ERROR control statements in the EXEC procedure 
ensure that if an error occurs during any part of the EXEC, the 
remainder of the EXEC does not execute, and the execution summary of the 
EXEC indicates the command that caused the error. 


Note that for the DLBL command entered with the DSN ? operand, you 
must stack the response before issuing the DLBL command. In this 
example, since the DOS file-id has more than eight characters, you must 
use the &BEGSTACK control statement to stack it. If you use the &STACK 
control statement, the EXEC processor truncates all words to eight 
characters. 


When your program is finished executing, the EXEC special variable 
SRETCODE indicates the contents of general register 15 at the time your 
program exited. You can use this value to perform additional steps in 
your EXEC procedure. Additional steps are indicated in the preceding 
example by ellipses. 


For detailed information on creating EXEC procedures, see "Part 3. 
Learning To Use EXECs." 
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Section 10. Using Access Method Services and VSAM 
Under CMS and CMS/DOS 


This section describes how you can use CMS to create and manipulate VSAM 
catalogs, data spaces, and files on OS and DOS disks using access method 
services. The CMS support is based on VSE/AF and VSE/VSAM; this means 
that if you are an OS VSAM user and plan to use CMS to manipulate VSAM 
files you are allowed to use those functions of access method services 
that are available under DOS/VS access method services. the access 
method services portion of VSE/VSAM. The control statements you can use 
are described in the publication Using VSE/VSAM Commands and Macros. 


You can use CMS to: 


e Execute the access method services utility programs for VSAM and SAM 
data sets on OS and DOS disks and minidisks. CMS can both read and 
write VSAM files using access method services. 


e Compile and execute programs that read and write VSAM files from DOS 
programs written in the COBOL or PL/I programming languages. 


e Compile and execute programs that read and write VSAM files from OS 
programs written in the VS BASIC, COBOL, or PL/I programming 
languages. 


VSAM files written under CMS are written using VSE/VSAM. Certain 
files written under CMS cannot be used directly by OS/VS VSAM. For 
information relative to compatibility between VSE/VSAM and OS/VS VSAM 
files, you should refer to the VSE/VSAM General Information Manual. 
None of the CMS commands normally used to manipulate CMS files are 
applicable to VSAM files, however. This includes such commands as PRINT, 
TYPE, EDIT, COPYFILE, and So on. 


This section provides information on using the CMS AMSERV command 
with which you can execute access method services. The discussion is 
divided as follows: 


e "Using the AMSERV command" contains general information. 


e "Manipulating OS and DOS Disks for Use With AMSERV" describes how to 
use CMS commands with OS and DOS disks. 


e "Defining DOS Input and Output Files" is for CMS/DOS users only. 
e "Defining OS Input and Output Files" is for OS users only. 


e "Using AMSERV Under CMS" includes notes and examples showing how to 
perform various access method services functions in CMS. 


EXECUTING VSAM PROGRAMS UNDER CMS 


The commands that are used to define input and output data sets for 
access method services (DLBL) and for CMS/DOS users (ASSGN) are also 
used to identify VSAM input and output files for program execution. 
Information on executing programs under CMS that manipulate VSAM files 
is contained in the program product documentation for the language 
processors. These publications are listed in the VWM/SP Introduction. 
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Restrictions on the use of access method services and VSAM under CMS 
for OS and DOS users are listed in VM/SP CMS Command and Macro 
Reference, which also contains complete CMS and CMS/DOS command formats, 
operand descriptions, and responses for each of the commands described 
here. 


When you are going to execute VSAM programs in CMS or CMS/DOS, you 
should remember to issue the DLBL command to identify the master 
catalog, as well as any other program input or output file you need to 
define. 


VSE/VSAM Release 2 has reduced its dependency on explicit ASSGN, 
EXTENT, and DLBL information. In many cases, this type of information 
need no longer be specified by the user. Identification of the master 
catalog within CMS, however, still requires ASSGN and DLBL commands. 


For complete inforamtion concerning the ASSGN, DLBL, and EXTENT 
requirements, refer to the VSE/VSAM Programmer's Reference. 


In the discussion that follows, ASSGN, DLBL, and EXTENT information 
is included even though it may not be required. 


Opening an ACB with a MACRF=ADR and subseguently issuing a GET ora 
PUT with KEYED ACCESS Specified in the RPL when SHAREOPTION (4) is 
specified, is not allowed in VSE/VSAM Release 2. Likewise, opening an 
ACB with KEYED ACCESS and subsequently issuing a GET or a PUT with 
MACRF=ADR specified in the RPL when SHAREOPTION (4) is specified is not 
allowed. Please refer to Using VSE/VSAM Commands and Macros for nore 
information. 


Using the AMSERV Command 


In CMS, you execute access method services utility programs with the 
AMSERV command, which has the basic format: 


amserv filename 


"filename" is the name of acCMS file that contains the control 
statements for access method services. 


Note: Throughout the remainder of this section the term "“AMSERV" is used 
to refer to both the CMS AMSERV command and the OS/VS or VSE/VSAM access 
method services, except where a distinction is being made between CMS 
and access method services. 


You create an AMSERV file with the CMS editor using a filetype of 
AMSERV and any filename you want; for example: 


edit mastcat amserv 
NEW FILE: 

EDIT: 

input 


The editor recognizes the filetype of AMSERV and so automatically sets 
the margins for your input lines at columns 2 and 72. The sample AMSERV 
file being created in the example above, MASTCAT AMSERV, might contain 
the following control statements: 


DEFINE MASTERCATALOG (NAME (MYCAT) - 


VOLUME (123456) CYL(2) - 
FILE (IJSYSCT) ) 
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Note that the syntax of the control statements must conform to the rules 
for access method services, including continuation characters and 
parentheses. The only difference is that the AMSERV file does not 
contain a "/*" for a termination indicator. 


Before you can execute the DEFINE control statement in this AMSERV 
example, you must define the output file, using the ddname IJSYSCT. You 
can do this using the DLBL command, if required by VSE/VSAH. Since the 
exact form required in the DLBL command varies according to whether you 
are an OS or a DOS user, separate discussions of the DLBL command are 
provided later in this section. All of the following examples assume 
that any disk data set or file that you are referencing with an AMSERV 
command will have been defined by a DLBL command, if required by 
VSE/VSAM. 


When you execute the AMSERV command, the AMSERV control statement 
file can be on any accessed CMS disk; you do not need to. specify the 
filemode and, if you are a DOS user, you do not need to assign SYSIPT. 
The task of locating the file and passing it to access method services 
is performed by CMS. 


AMSERV OUTPUT LISTINGS 


When the AMSERV command is finished processing, you receive the CMS 
ready message, and if there was an error, the return code (from register 
15) is displayed following the "R". For example: 


R (00008) ; 

or, if you are receiving the long form of the ready message, it appears: 
R (00008); T=0.01/0.11 10:50:23 

If you receive a ready message with an error return code, you should 


examine the output listing from AMSERV to determine the cause of the 
error. 


AMSERV output listings are written in CMS files with a filetype of 
LISTING; by default, the filename is the same as that of the input 
AMSERV file. For example, if you have executed: 


amserv mastcat 


and the CMS ready message indicates an error return code, you should 
examine the file MASTCAT LISTING: 


edit mastcat listing 
EDIT: 
locate /idc/#= 


Issuing the LOCATE subcommand twice to find the character string IDC 
will position you in the LISTING file at the first access’ method 
services message. 


TD EE ERT EE ES NTE 


the messages generated by access method services together with the 
associated return and reason codes. 


Instead of editing the file, you could also use the TYPE command to 
display the contents of the entire file, so that you would be able to 
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examine the input control statements as well as any error messages: 
type mastcat listing 


If you need to make changes to control statements before executing 
the AMSERV command again, use the CMS editor to modify the AMSERV input 
file. 


If you execute the same AMSERV file a number of times, each execution 
results in a new LISTING file, which replaces any previous listing file 
with the same filename. 


Output from PRINT, LISTCAT, and LISTCRA 


When you use AMSERV to print a VSAM file, or to list catalog or recovery 
area contents using the PRINT, LISTCAT, or LISTCRA control statements, 
the output is written ina listing file on a CMS’ read/write disk, and 
not spooled to the printer unless you use the PRINT option of the AMSERV 
command: 


amserv listcat (print 


If you want to save the output, you should issue the AMSERV command 
without the PRINT option and then use the CMS PRINT command to print the 
LISTING file. 


CONTROLLING AMSERV COMMAND LISTINGS 


The final disposition of the listing, as a printer or disk file, depends 
on how you enter the AMSERV command. If you enter the AMSERV conmand 
with no options, you get a CMS file with a filetype of LISTING anda 
filename equal to that of the AMSERV input file. This LISTING file is 
usually written on your A-disk, but if your A-disk is full or not 
accessed, it is written onany other read/write CMS disk you have 
accessed. 


If there is not enough room on your A-disk or any other disk, the 
AMSERV command issues an error message saying that it cannot write the 
LISTING file. If this happens, the LISTING file created may be 
incomplete and you may not be able to tell whether or not access method 
services actually completed successfully. In this case, after you have 
cleared some space on a read/write disk, you may have to execute an 
AMSERV PRINT or LISTCAT function to verify the completion of the prior 
job. 


LISTING files take up considerable disk space, so you should erase 
them as soon as you no longer need then. 


AMSERV Command Listing Options 


TTT 


If you do not want AMSERV to create a disk file from the listing, you 
can execute the AMSERV command with the PRINT option: 


amserv nyfile (print 


The listing is spooled to your virtual printer, and no disk file is 
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created. You might want to use this option if you are executing a PRINT 
or LISTCAT control statement and expect a very large output listing that 
you know cannot be contained on any of your disks. 


You can also control the filename of the output listing file by 
specifying a second name on the AMSERV command line: 


amserv listcat listcatl1 


In this example, the input file is LISTCAT AMSERV and the output listing 
is placed ina file named LISTCAT1 LISTING. A subsequent execution of 
this same AMSERV file: 


amserv listcat listcat2 


creates a second listing file, LISTCAT2 LISTING, so that the listing 
created from the first execution is not erased. 


Manipulating OS and DOS Disks for Use with AMSERV 


To use CMS VSAM and AMSERV, you can have OS or DOS disks in your virtual 
machine configuration. They can be assigned in your directory entry, or 
you can link to them using the CP LINK command. You must have read/write 
access to them in order to execute any AMSERV function or VSAM progran 
that requires opening the file for output or update. 


Before you can use an OS or DOS disk you must access it with the CMS 
ACCESS command: 


access 200 d 


The response from the ACCESS command indicates that the disk is in OS or 
DOS format: 


D(200) R/W - OS 
D(200) R/W - DOS 


You can write on these disks only through AMSERV or through the 
execution of a program writing VSAM data sets. Once an OS disk is used 
with AMSERV or VSAM, CMS considers it a DOS disk, so regardless of 
whether you are an OS user, when you access or request information about 
a VSAM disk, CMS indicates that it is a DOS disk. You can still use the 
disk in an OS or DOS system for VSAM data set processing. Although the 
format is not changed, the disk is still subject to any 
incompatibilities that can currently exist between OS and DOS disks. 


DATA AND MASTERCATALOG SHARING 


There are two meanings of "Sharing" that must be defined clearly with 
respect to the CMS support of VSAM. The first is that of the 
SHAREOPTION parameter found in the DEFINE (and ALTER) command for access 
method services. 


The SHAREOPTION keyword enables the VSAM user to define how a 


component will be shared within or across VSE/AF partitions and VSE/AF 
systems. Since CMS supports only a single partition environment, cross 
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partition sharing has no meaning in the CMS environment. In addition, 
Since CMS does not provide DASD sharing support, cross system sharing is 
not supported. Consequently, the SHAREOPTION parameter only has neaning 
within a CMS virtual machine (functional equivalent of a VSE/AF 
partition). 


The area of sharing most familiar to CMS users is that of disk 
(minidisk) read-sharing provided by CP. For the VSAM user under CMS, it 
is still possible to share disks in read-only mode in order to 
read-share VSAM components. However, there is a restriction with 
respect to the VSAM master catalog. That is, only one virtual machine 
may have the disk containing the master catalog in write status. This 
is necessary even if only read functions are being performed during the 
session. This is due to the master catalog updating read statistics at 
close time and, when necessary, writing a new control record in the 
catalog at open time. 


Under CMS, it is possible to have the master catalog disk read-only. 
A programming modification (a bit inthe ACB) was made to the DOS/VS 
VSAM code so that VSAM knows it is running under CMS. If this bit is 
on, VSAM will not write to the master catalog for either of the two 
cases described above. This allows one or more CMS virtual machines to 
Share the VSAM master catalog. This assumes either no other virtual 
machine has the master catalog disk in write status or only one virtual 
machine (DOS, OS, or CMS) has it. 


Multiple CMS users may have the VSAM master catalog disk in read-only 
status but only one virtual machine may have the same in write status. 
With respect to dataset sharing, there is only read-sharing for the CMS 
user. 


DISK COMPATIBILITY 


Since the CMS VSAM support writes VSAM datasets to DOS disks, the 
question of disk compatibility is not one between CMS and DOS nor 
between CMS or OS but rather between DOS and OS disks. In other words, 
because CMS actually uses VSE/VSAM for processing VSAM datasets, all 
disks used by CMS VSAM are DOS disks. For this reason, we need only 
discuss how DOS and OS disks are compatible and, because they are 
compatible, we can conclude that CMS and OS are also compatible. 


In the format-4 DSCB, there is a bit in the VTOC Indicators (byte 59, 
bit 0) defined by OS/VS to indicate (when OFF) that a format-5 label is 
included in the VTOC. This bit is always ON under VSE/AF because DOS 
does not maintain the format-5 label. This technique allows OS/VS to 
realize when the format-5 is invalid and that it must recompute free 
space and rewrite the format-5 so that device integrity is maintained. 


Thus, if a disk originally was used (allocated) under OS/VS and, 
subsequently, with VSE/AF further allocation could occur under VSE/AF 
but with the format-5 ignored and, therefore, no longer valid. If the 
disk was then used under OS/VS and still further allocation performed, 
OS/VS would recognize the fact that the format-5 was not valid 
(contamination bit turned ON by VSE/AF and would rewrite the format-5, 
turning the bit OFF. 


In terms of space allocation, this shows that DOS and OS disks are 
compatible in that they are portable between the two systems, but one of 
the systems (OS/VS) must perform some extra processing (rewriting 
format-5) prior to using the disk if it intends to reallocate using the 
format-—5. 
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DOS and OS disks containing VSAM datasets are no exception to this. 
OS and DOS disks containing VSAM datasets that are used (allocated) 
under CMS are portable among all three systems. Since CMS uses VSE/VSAM 
code, all disks used under CMS to process VSAM datasets become DOS disks 
in that the contamination bit is turned ON as it is when using VSE/AF. 


The term "minidisk" may be interchanged with the word "disk" in the 
above explanation if we are dealing with "virtual" VSE/AF and OS/VS 
systems. However, real systems are not aware of, and do not support, 
minidisks. 


VSE/VSAM uses physical record sizes ranging from .5K bytes to 8K 
bytes. All multiples of .5K bytes between those two values are 
supported. OS/VS VSAM, however, only supports physical record sizes of 
-5K, 1K, 2K, and 4K. Therefore, certain VSAM files written under CMS 
cannot be used directly by OS/VS VSAM. 


It is necessary to distinguish between two types of allocation under 
VSAM. The first refers to actual space allocation on the disk, and the 
second is that within the dataset itself. 


Space for VSAM components must be allocated on the DASD using the 
DEFINE commands. The only component for which the user is able to 
allocate space is for the master catalog, a user catalog, a data space, 
and a UNIQUE cluster. In defining the actual DASD space for components, 
there are parameters for the DEFINE SPACE command which allows the user 
to include a "secondary allocation" specification. These parameters 
(CYLINDERS, RECORDS, BLOCKS, TRACKS) have this secondary facility only 
as asyntactic compatibility with the OS/VS access method services 
commands. That is, VSE/AF (and, therefore, CMS) does not perform 
secondary space allocation on a DASD. 


The facility does exist under VSE/AF (and CMS) to extend data or 
index components through already allocated data space, catalog extents, 
or UNIQUE cluster extents. Thus, the CYLINDERS, TRACKS, RECORDS, and 
BLOCKS parameters of the DEFINE commands for alternate indexes, 
clusters, and catalogs do not dynamically allocate DASD space but only 
extend a component through existing space. 


USING VM/SP MINIDISKS 


If you have a VM/SP minidisk in your virtual machine configuration, you 
can use it to contain VSAM files. Before you can use it, it must be 
formatted with the DSF program. When you request that a disk be added 
to your virtual machine configuration for use with VSAM files under CMS, 
you should indicate that it be formatted for use with OS or DOS. Or you 
can format it yourself using the DSF program. A brief example of how to 
do this is given under the following "Using Temporary Disks." 


Note: If you are an OS user, you should be careful about allocating 
space for VSAM on minidisks. Once you have used CMS AMSERV to allocate 
VSAM data space on a minidisk, you should not attempt to allocate 
additional space on that minidisk using an OS/VS system. OS does not 
recognize minidisks, and would attempt to format the entire disk pack 
and thus erase any data on it. To allocate additional space for VSAM, 
you should use CMS again. 


Minidisk space allocation is fully described in the VM/SP Planning and 
System Generation Guide. 
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USING THE LISTDS COMMAND 


For OS or DOS disks or minidisks, you can use the LISTDS command to 
determine the extents of free space available for use by VSAM. You can 
also determine what space is already in use. You can use this 
information to supply the extent information when you define VSAM files. 


The options used with VSAM disks are: 


e EXTENT, to find out what extents are in use, and 
e FREE, to find out what extents are available. 


For example, if you have an OS disk accessed as a G-disk, and you enter: 
listds g (extent 
The response might look like: 
EXTENT INFORMATION FOR "'VTOC* ON 'G* DISK: 
SEQ TYPE CYL-HD(RELTRK) TO CYL-HD(RELTRR) TRACKS 
000 vtoc 099 00 1881 099 18 1899 19 
EXTENT INFORMATION FOR "PRIVAT.CORE.IMAGE.LIB' ON 'G* DISK: 
SEQ TYPE CYL-HD(RELTRK) TO CYL-HD(RELTRR) TRACKS 
000 DATA 000 01 1 049 18 949 949 
EXTENT INFORMATION FOR "SYSTEM.WORK.FILE.-NO.6" ON 'G* DISK: 


SEQ TYPE CYL-HD(RELTRK) TO CYL-HD(RELTRK) TRACKS 
000 DATA 050 00 950 051 18 987 38 


You could also determine the extent for a particular data set: 
listds ? * (extent 
DMSLDS220R ENTER DATA SET NAME: 
system. recorder. file 
The response night look like: 
EXTENT INFORMATION FOR ‘SYSTEM RECORDER FILE® ON 'F* DISK: 
SEQ TYPE CYL-HD(RELTRK) TO CYL-HD(RELTRR) TRACKS 
000 DATA 102 00 1938 102 18 1956 19 
002 DATA 010 06 206 010 08 208 3 
LISTDS searches all minidisks accessed until it locates the specified 
data set. In this example, the data set occupies two separate extents on 
disk F. If the data set isa nmultivolume data set, extents on all 
accessed volumes are located and displayed. 
If you want to find the free extents on a particular disk, enter: 
listds g (free 


The response might look like: 


FREESPACE EXTENTS FOR 'G* DISK: 
CYL-HD (RELTRK) TO CYL~HD (RELTRR) TRACKS 


052 00 988 052 01 989 2 
054 02 1028 080 00 1520 493 
081 01 1540 098 18 1880 341 


You can use this information when you allocate space for VSAM files. If 
you enter: 
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listds * (free 


CMS lists all the free space available on all of your accessed disks. 


USING TEMPORARY DISKS 


When you need extra space on a temporary basis for use with CMS VSAM and 
AMSERV, you can use the CP DEFINE command to define a temporary minidisk 
and then use the Device Support Facilities (DSF) program to format it. 
(Refer to the Device Support Facilities User's Guide and Reference, 
GC 35-0033.) Once formatted and accessed, it is available to your 
virtual machine for the duration of your terminal session or until you 
detach it using the CP DETACH command. Remember that anything placed on 
a temporary disk is lost, so that you should copy output that you want 
to keep onto permanent disks before you log off. 


Formatting a Temporary Disk 


The example below shows a control statement file and an EXEC procedure 
that, together, can be used to format a minidisk with the DSF progran. 
For a complete description of the control statements used, refer to the 


VWM/SP Operator's Guide. 


The input control statements for the DSF programs should be placed in 
a CMS file, so that they can be punched to your virtual card reader. For 
this example, suppose the statements are in a CMS file named TEMP DSF: 


INIT UNIT(198) DEVTYP (3340) PRG NVFY VOLID (123456) DVTOC(9,7,5) - 
MIMIC (MINI (10)) 


(Note: the above begins in column 2) 
Now consider the CMS file named TEMPDISK EXEC: 


SCONTROL OFF 

SERROR &EXIT 100 

CP DEFINE T3340 198 10 

CP CLOSE READER 

CP PURGE READER CLASS I 

CP SPOOL PUNCH TO * CLASS I CONT NOHOLD 
PUNCH IPL DSF * (NOH) 

PUNCH TEMP DSF * (NOH) 

CP SPOOL PUNCH NOCONT CLOSE 

CP SPOOL READER CLASS I NOHOLD 
CP IPL 00C CLEAR ATTN 


You execute this procedure by entering the filename of the EXEC: 
tempdisk 


When the final line of this EXEC is executed, the DSF program is in 
control. 


ICKOOSE DEFINE INPUT DEVICE, REPLY 'DDDD,CUU OR CONSOLE! 
ENTER INPUT/COMMAND: 


You should enter: 


2540,00c 
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to 


indicate that the control statements should be read from your card 


reader, which is a virtual 2540 device at virtual address 00C. 


ICKOO6E DEFINE OUTPUT DEVICE, REPLY *DDDD,CUU OR CONSOLE! 
ENTER INPUT/COMMAND: 


You should enter: 


to 


console 
indicate that the utility output should sent to your console. 


ICKO03D REPLY U TO ALTER VOLUME 198 CONTENTS, ELSE T 
ENTER INPUT/COMMAND: 


Reply to ICKOO3D: 


to 


sta 


u 


continue the execution. 


When the DSF program is completes, your virtual machine is in a wait 
te and you must reload CMS (with the IPL command) to begin virtual 


Machine execution. You can then access the temporary disk: 


acc 198 c 


and CMS responds: 


C (198) R/W - DOS 


Defining DOS Input and Output Files 


Note: This information is for VSE/VSAM users. OS/VS VSAM users should 
refer to the section "Defining OS Input and Output Files." 


You may use the DLBL command to define VSAM input and output files 


for both the AMSERV command and for program execution. The operands 
required on the DLBL command are: 


dlbl ddname filemode DSN datasetname (options SYSxxx 


where "ddname" corresponds to the FILE parameter in the AMSERV file and 
"datasetname" corresponds to the entry name or filename of the VSAM 
file. 


to 
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There are several options you can use when issuing the DLBL command 
define VSAM input and output files. These are: 


VSAM, which you must use to indicate that the file is a VSAM file. 


Note: You do not have to use the VSAM option to identify a file as a 
VSAM file if you are using any of the other options listed here, 
since they imply that the file is a VSAM file. In addition, the 
ddnames (filenames) IJSYSCT and IJSYSUC also indicate that the file 
being defined is a VSAM file. 


EXTENT, which you may use when you are defining a catalog or a VSAM 
data space; you are prompted to enter the volume information. This 
option effectively provides the function of the EXTENT card in 
VSE/AF. 


IBM VM/SP CMS User's Guide 


e MULT, which you must use in order to access a nultivolume VSAM file; 
you are prompted to enter the extent information. 


e CAT, which you can use to identify a catalog which contains the entry 
for the VSAM file you are defining. 


e BUFSP, which you can use to specify the size of the buffers VSAM 
should use during program execution. 


Options are entered following the open parenthesis on the DLBL command 
line, with the SYSxxx: 


assgn sys003 e 
dlbl file1l b1 dsn workfile (extent cat cat2 sys003 


USING VSAM CATALOGS 


While you are developing and testing your VSAM programs in CMS, you may 
find it convenient to create and use your own master catalog, which may 
be on aCMS minidisk. VSAM catalogs, like any other cluster, can be 
shared read-only among several users. 


You name the VSAM master catalog for your terminal sesSion using the 
logical unit SYSCAT in the ASSGN command and the ddname IJSYSCT for the 
DLBL command. For example, if your VSAM master catalog is located on a 
DOS disk you have accessed as a C-disk, you would enter: 


assgn syscat c 
dlbl ijsysct c dsn mastcat (syscat 


Note: When you use the ddname IJSYSCT you do not need to specify the 
VSAM option on the DLBL command. 


You must identify the master catalog at the start of every terminal 
session. If you are always using the same master catalog, you might 
include the ASSGN and DLBL commands in an EXEC procedure or in your 
PROFILE EXEC. You could also include the commands necessary to access 
the DOS system residence volume and enter the CMS/DOS environment: 


ACCESS 350 Z 

SET DOS OW Z (VSAM 

ACCESS 555 C 

ASSGN SYSCAT C 

DLBL IJSYSCT C DSN MASTCAT (SYSCAT PERM 


You should use the PERM option so that you do not have to reset the 
master catalog assignment after clearing previous DLBL definitions. 


You must use the VSAM option on the SET DOS ON command line if you 
want to use any access method services function or access VSAM files. 


Defining a Master Catalog 


The sample ASSGN and DLBL commands used in the above EXEC are almost 
identical to those you issue to define a master catalog using AMSERV. 
The only difference is the EXTENT option which lists the data spaces 
that this master catalog is to control. 


As an example, suppose that you have a 30-cylinder 3330 minidisk 
assigned to you to use for testing your VSAM programs under CMS. 
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Assuming that the minidisk is in your directory at address 333, you 
should first access it: 


access 333 da 
D(333) R/W - OS 


If you formatted the minidisk yourself, you know what its label is. If 
not, you can find out what the label is by using the CMS command: 


query search 
The response night be: 


USR191 191 A R/W 
DO0S333 333 OD R/W — OS 
SY¥S190 190 S§ R/O 
SYS19E 19E Y/S R/O 


Use the label DOS333 in the VOLUMES parameter in the MASTCAT AMSERV 
file: 


DEFINE MASTERCATALOG - 
(NAME (MASTCAT ) - 
VOLUME (DOS333) - 
CYL (4) - 

FILE (IJSYSCT) ) 


To find out what extents on the minidisk you can allocate for VSAM, 
use the LISTDS command with the FREE option: 


listds d (free 
The response from LISTDS might look like this: 


FREESPACE INFORMATION FOR 'D* DISK: 
CYL-HD(RELTRK) TO CYL-HD(RELTRK) TRACKS 
000 01 1 000 09 9 9 
000 11 11 029 18 569 560 


From this response, you can see that the volume table of contents (VTOC) 
is located on the first cylinder, so you can allocate cylinders 1 
through 29 for VSAM: 


assgn syscat d 
dlbl ijsysct ddsn mastcat (syscat perm extent 
DMSDLB331R ENTER EXTENT SPECIFICATIONS: 
19 551 
(null line) 


After entering the extents, in tracks, giving the relative track number 
of the first track to be allocated followed by the number of tracks, you 
must enter a null line to complete the command. A null line is required 
because, when you enter multiple extents, entries may be placed on more 
than one line. If you do not enter a null line, the next line you enter 
causes an error, and you must re-enter all of the extent information. 
Note that, as in VSE/AF the extents must be on cylinder boundaries, and 
you cannot allocate cylinder 0. 


Now you can issue the AMSERV command: 
amserv mastcat 
A ready message with no return code indicates that the master catalog is 


defined. You do not need to reissue the ASSGN and DLBL commands in order 
to use the master catalog for additional AMSERV functions. 
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Defining User Catalogs 


You can use the AMSERV command to define private catalogs and spaces for 
them, also. The procedures for determining what space you can allocate 
are the same as those outlined in the example of defining a master 
catalog. 


For a user catalog, you may use any programmer logical unit, and any 
ddname: 


access 199 e 
listds e (free 


assgn sys001 e 
dlbl cati e dsn private.cat1 (sys001 extent pern 


amserv usercat 
The file USERCAT AMSERV might contain the following: 


DEFINE USERCATALOG - 
(NAME (PRIVATE.CAT1) - 
FILE (IdJSYSUC) - 
CYL (4) - 
VOLUME (DOSVS2) - 
CATALOG (MASTCAT) ) 


After this AMSERV command has comfleted successfully you can’ use the 
catalog PRIVATE.CAT1. When you issue a DLBL command to identify a 
cluster or data set cataloged in this catalog, you must identify the 
catalog using the CAT option on the DLBL command for the file: 


assgn sys100 c 
dlbl file2 c dsn ? (sys100 cat cat1 


Or, you can define this catalog as a job catalog. 


Using a Job Catalog 


If you want to set up a user catalog as a job catalog so that it will be 
searched during all subseguent jobs, you can define the catalog using 
the special ddname IJSYSUC. For example: 


assgn sys101 c 
dlbl ijsysuc c dsn private.cat1 (sys101 perm 


If you defined a user catalog (IJSYSUC) for a terminal session and 
you use the AMSERV command to access a VSAM file, the user catalog takes 
precedence over the master catalog. This means that for files’ that 
already exist, only the user catalog is searched. When you define a 
cluster, it is cataloged in the user catalog, rather than in the master 
catalog, unless you use the CAT option to override it. 


If you want to use additional catalogs during a terminal session, you 
first define them just as you would any other VSAM file: 
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assgn sys010 f 
dlbl mycat2 £ dsn private.cat2 (sys010 vsanm 


Then, when you enter the DLBL command for the VSAM file that is 
cataloged in PRIVATE.CAT2 use the CAT option to refer to the ddname of 
the catalog: 


assgn sys0O11 £ 
dlbl input £ dsn input.file (sys011 cat mycat2 


If you want to stop using a job catalog defined as IJSYSUC, you can 
clear it using the CLEAR option of the DLBL command: 


dlbl ijsysuc clear 


Then, the master catalog becomes the job catalog for files not defined 
with the CAT option. 


Catalog Passwords 


When you define passwords for VSAM catalogs in CMS, or when you use CMS 
to access VSAM catalogs that have passwords associated with them, you 
must supply the password from your terminal when the AMSERV command 
executes. The message that you receive to prompt you for the password 
is the same message you receive when you execute access method services: 


4221A ATTEMPT 1 OF 2. ENTER PASSWORD FOR JOB AMSERV FILE catalog 


When you enter the proper password, AMSERV continues execution. 


DEFINING AND ALLOCATING SPACE FOR VSAM FILES 


You can use CMS AMSERV to allocate additional data spaces for VSAM. To 
use the DEFINE SPACE control statement, you must have defined the 
catalog that is to control the space, and you must have the volume or 
volumes on which the space is to be allocated mounted and accessed. 


For example, suppose you have a DOS-formatted 3330 disk attached to 
your virtual machine at virtual address 255. After accessing the disk 
and determining the free space on it, you could create a file named 
SPACE AMSERYV: 


DEFINE SPACE - 
(FILE (FILE1) - 
TRACKS (1900) - 
VOLUME (123456) - 
CATALOG (PRIVATE.CAT2 CAT2) ) 


To execute this AMSERV file, define PRIVATE.CAT2 as a user catalog using 
the ddname CAT2, and then define the ddname for the FILE parameter: 


access 255 c 

assgn sys010 c 

dlbl cat2 c dsn private.cat2 (sys010 vsan 
assgn sys011 c 

dlbl filel c (extent sys011 cat cat2 


Note that you do not need to enter a data set name to define the space. 
When CMS prompts you for the extents of the space you can enter the 


218 IBM VM/SP CMS User's Guide 


extent specifications: 


DMSDLB331R ENTER EXTENT SPECIFICATIONS: 
190 1900 


When you define space for VSAM, you should be sure that the VOLUMES 
parameter and the space allocation parameter (whether CYLINDER, TRACKS, 
BLOCKS, or RECORDS) in the AMSERV file agrees with the information you 
provide in the DLBL command. All data extents must begin and end on 
cylinder boundaries. Any additional space you provide in the extent 
information that is beyond what you specified in the AMSERV file is 
Claimed by VSAM. 


Specifying Multiple Extents 


When you are specifying extents for a master catalog, data space, or 
unigue file, you can specify up to 16 extents on a volume for a 
particular space. When prompted by CMS to enter the extents, you must 
separate different extents by commas or place them on different lines. 
To specify a range of extents in the above example, you can enter: 


dlbl filel c (extent sys011 
190 190, 570 190, 1900 1520 
(null line) 


dlbl filel c (extent sys011 


190 190 
570 190 
1900 1520 


(null line) 


Again, the first number entered for each extent represents the relative 
track for the beginning of the extent and the second number indicates 
the number of tracks. 


Specifying Multivolume Extents 


You can define spaces that span up to nine volumes for VSAM files; all 
of the volumes must be accessed and assigned when you issue the DLBL 
command to define or identify the data space. 


You should remember, though, that if you are using AMSERV and you do 
not use the PRINT option, you must have a read/write CMS disk so that 
AMSERV can write the output LISTING file. 


If you are defining a new mnultivolume data space or unique cluster, 
you must specify the extents on each volume that the data is to occupy 
(starting track and number of tracks), followed by the disk node letter 
at which the disk is accessed and the programmer logical unit to which 
the disk is assigned: 
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access 135 b 
access 136 c 
access 137 d 
assgn sys001 b 
assgn sys002 c 
assgn sys003 d 
dlbl newfile b (extent sys001 
DMSDLB331R ENTER EXTENT SPECIFICATIONS: 
100 60 b sys001, 400 80 b sys001, 60 40 d sys003 
2000 100 c sys002 
(null line) 


If you specify more than one extent on the same line, the extents must 
be separated by commas; if you enter a comma at the end of a line, it is 
ignored. Different extents for the same volume must be entered 
consecutively. 


Note that in the preceding example, the extent information is for 
2314 disks; and that these extents are also on cylinder boundaries. 


When you enter nultivolume extents you can use a default mode. For 
example: 


dlbl newfile b (extent sys001 
DMSDLB331R ENTER EXTENT SPECIFICATIONS: 
100 60, 400 80, 60 40 d sys003, 
2000 100 c sys002 

(null line) 


Any extents you enter without specifying a mode letter and SYSxxx value 
default to the mode and SYSxxx on the DLBL command line, in this case, 
the B-disk, SYS001. 


If you make any errors issuing the DLBL command or extent 
information, you must re-enter the entire command sequence. 


IDENTIFYING EXISTING MULTIVOLUME FILES: When you issue a DLBL command to 
identify an existing multivolume VSAM file, you must use the MULT option 
of the DLBL command: 


dlbl old b1 dsn ? (sys002 mult 
DMSDLB220R ENTER DATA SET NAME? 
dostest. file 
DMSDLB330R ENTER VOLUME SPECIFICATIONS: 
c sys004, d sys003 
e sys007 

(null line) 


When you enter the DLBL command you should specify the mode letter and 
logical unit for the first volume on the command line. When you enter 
the MULT option you are prompted to enter additional specifications for 
the remaining extents. In the preceding example, the data set has 
extents on disks accessed as B-, C-, D-, and E-disks. 


USING TAPE INPUT AND OUTPUT 


If you are using AMSERV for a function that requires tape input and/or 
output, you must have the tape(s) attached to your virtual machine. The 
valid addresses for tapes are 181, 182, 183, and 184. When referring to 
tapes, you can also refer to them using their CMS symbolic names TAP1, 
TAP2, TAP3, and TAP4. 


For AMSERV functions that use tape input/output, the TLBL control 
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statement is Simulated by building a dummy DLBL containing a 
user-supplied ddname (filename). CMS does not read tape labels and does 
not recognize tape data set names. 


When you invoke the AMSERV command, you must use the TAPIN or TAPOUT 
option to specify the tape device being used: 


amserv export (tapout 181 


In this example, the output from the AMSERV control statements ina file 
named EXPORT goes to a tape at virtual address 181. CMS prompts you to 
enter the ddname: 


DMSAMS367R ENTER TAPE OUTPUT DINAMES: 


After you enter the ddname specified on the FILE parameter in the AMSERV 
file and press the carriage return, the AMSERV command executes. 


AMSERV opens all tape files as standard labelled tapes or 
non-labelled tapes. If you are using standard labelled tapes, you need 
to specify a LABELDEF command with AMSERV. The LABELDEF command is the 
CMS/DOS equivalent of VSE/AF TLB control statement. The LABELDEF 
command is used to specify information in VOL1 and HDR1 labels’ on the 
tape. See the description of the LABELDEF command in section 7 for nore 
information on this command. 


You should use the same name for the filename on your LABELDEF 
command as you do for the ddname you enter in reply to message 
DMSAMS367R (the ddname specified on the FILE parameter in the AMSERV 
file). However, the LABEFLDEF command must be issued before the AMSERV 
command. The following sequence of commands might be used when you have 
Standard labelled tape output. 


assgn sys005 tap1 

tape rew (181 

assgn syscat e 

assgn sys006 e 

labeldef catout fid catfile volid amserv 
dlbl ijsysct e dsn mastcat (syscat vsan 
dlbl catin e dsn file (sys006 vsan 
amserv repro (tapout 181 


DMSAMS367R ENTER TAPE OUTPUT DDNAMES 

catout 
Note: If you do not care what is written in a tape output label or do 
not want input labels checked, you can specify a LABELDEF with no 
parameters other than filename. 

The command: 

labeldef intape 
used for an input tape with ddname INTAPE causes the standard labels on 
the tape to be skipped without any checking. A similar statement for 
output writes tape labels with default values (see the description of 
the LABELDEF command in section 7). 


If you use non-labelled tapes, LABELDEF is not required. 
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When you create a tape in CMS using AMSERV, CMS writes a tape mark 
preceding each output file that it writes. When the same tape is read 
using AMSERV under CMS, HDR1 and VOL1 labels are checked using the 
LABELDEF command you provide. If you read this tape in a real VSE/AF 
system, you should use a TLBL card instead of the LABELDEF command. 


Similarly, when you create a tape under a VSE/AF system using access 
method services, if the tafe is created with standard labels, CMS AMSERV 
has no difficulty reading it. 


The only time you should worry about positioning a tape created by 
AMSERV is when you want to read the tape using a method other than 
AMSERV, for example, the MOVEFILE command. Then, you must forward space 
the tape past the label, using the CMS TAPE command before you can read 
it. 


Defining OS Input and Output Files 


Note: This information is for OS/VS VSAM users only. VSE/VSAM users 
should refer to "Defining DOS Input and Output Files" for information on 
defining files for use with VSAM. 


The OS/VS VSAM user should bear in mind that CMS uses VSE/VSAM to 
Manipulate VSAM files. The VSAM and AMS statements that can be used are 
described in the publication Using VSE/VSAM Commands and Macros. 


In addition, there are certain incompatibilities between VSE/VSAM and 
OS/VS VSAM. For a description of these incompatibilities, refer to the 
NSE/VSAM General Information Manual. 


If you are going to use access method services to manipulate VSAM or 
SAM files or you are going to execute VSAM programs under CMS, use the 
DLBL command to define the input and output files. The basic format of 
the DLBL command is: 


DLBL ddname filemode DSN datasetname (options 


where ddname corresponds to the FILE parameter in the AMSERV file and 
datasetname corresponds to the entry name of the VSAM file, that is, the 
name specified in the NAME parameter of an access nethod services 
control statement. 


If you are using a CMS file for AMSERV input or output, use the CMS 
operand and enter CMS file identifiers as follows: 


dlbl mine a cms out filel (vsan 


The maximum length allowed for ddnames under CMS VSAM iS’ seven 
characters. This means that if you have assigned eight-character ddnames 
(or filenames) to files in your programs, only the first seven 
characters of each ddname are used. So, if a program refers’ to the 
ddname OUTPUTDD, you should issue the DLBL command for a ddname of 
OUTPUTD. Since you can encounter problems with a program that contains 
ddnames with the same first seven characters, you should recompile those 
programs using seven-character ddnames. 


There are several options you can use when issuing the DLBL command 
to define VSAM input and output files. These are: 
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e VSAM, which you must use to indicate that the file is a VSAM file. 


Note: You do not have to use the VSAM option to identify a file as a 
VSAM file if you are using any of the other options listed here, 
since they imply that the file is a VSAM file. In addition, the 
ddnames (filenames) IJSYSCT and IJSYSUC also indicate that the file 
being defined is a VSAM file. 


e EXTENT, which you can use when you are defining a catalog or a VSAM 
data space; you are prompted to enter the volume information. 


e MULT, which you must use in order to access a multivolume VSAM file; 
you are prompted to enter the extent information. 


e CAT, which you can use to identify a catalog which contains the entry 
for the VSAM file you are defining. 


e BUFSP, which you can use to specify the size of the buffers VSAM 
should use during program execution. 


ALLOCATING EXTENTS ON OS DISKS AND MINIDISKS 


When you use access method services to manipulate VSAM files under OS, 
you do not have to worry about allocating the real cylinders and tracks 
to contain the files. You can, however, use CMS commands’ to indicate 
which cylinders and tracks should contain particular VSAM spaces when 
you use the DEFINE control statement to define space. 


Extents for VSAM data spaces can be defined, in AMSERV files, in 
terms of cylinders, tracks, or records. Extent information you supply to 
CMS when executing AMSERV must always be in terms of tracks. When you 
define data spaces or unigue clusters, the extent information (number of 
cylinders, tracks, or records) in the AMSERV file must match the extents 
you supply when you issue the DLBL command to define the file. When you 
supply extent information for the master catalog, any extents you enter 
in excess of those reguired for the catalog are claimed by the catalog 
and used as data space. 


CMS does not make secondary space allocation for VSAM data spaces. 
If you execute an AMSERV file that specifies a secondary space 
allocation, CMS ignores the parameter. 


When you use the DLBL command to define VSAM data Space, you can use 
the EXTENT option, which indicates to CMS that you are going to enter 
data extents. For example, if you enter: 


dlbl space b (extent 
CMS prompts you to enter the extents: 

DMSDLB331R ENTER EXTENT SPECIFICATIONS: 
When you enter the extents, you specify the relative track number of the 
first track of the extent, followed by the number of tracks. For 


example, if you are allocating an entire 2314 disk, you would enter: 


20 3980 
(null line) 


You can never write on cylinder 0, track 0; and, since VSAM data 
Spaces must be allocated on cylinder boundaries, you should never 
allocate cylinder 0. Cylinder 0 is often used for the volume table of 
contents (VTOC) as well, so it is aiways best to begin defining space 
with cylinder 1. 
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You can determine which disk extents on an OS disk or minidisk are 
available for allocation by using the LISTDS command with the FREE 
option, which also indicates the relative track numbers, as well as 
actual cylinder and head numbers. 


USING VSAM CATALOGS 


While you are developing and testing your VSAM programs in CMS, you may 
find it convenient to create and use your own master catalog, which may 
be on acCMS minidisk. VSAM catalogs, like any other cluster, can be 
shared read-only among several users. 


You name the VSAM master catalog for your terminal session using the 
ddname IJSYSCT for the DLBL command. For example, if your VSAM master 
catalog is located on an OS disk you have accessed as a C-disk, you 
would enter: 


dlbl ijsysct c dsn master catalog (perm 


You must define the master catalog at the start of every terminal 
session. If you are always using the same master catalog, you night 
include the DLBL command you need to define it in your PROFILE EXEC: 


ACCESS 555 C 
DLBL IJSYSCT C DSN MASTCAT (PERM 


You should use the PERM option so that you do not have to reset the 
master catalog assignment after clearing previous DLBL definitions. The 
command: 


dlbl * clear 


Clears allt file definitions except those entered with the PERM option. 


Defining a Master Catalog 


The sample DLBL command used in the preceding example is almost 
identical with the one you would issue to define a master catalog using 
AMSERV. The only difference is that you can enter the EXTENT option so 
that you can list the data spaces that this master catalog is to 
control. 


As an example, suppose that you have a 30-cylinder 3330 minidisk 
assigned to you to use for testing your VSAM programs under CMS. 
Assuming that the minidisk is in your directory at address 333, you 
should first access it: 


access 333 d 
D (333) R/W - OS 


If you formatted the minidisk yourself, you know what label you assigned 
it; if not, you can find out the label assigned to the disk by issuing 
the CMS command: 

query search 


The response might be: 
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USR191 191 A R/W 
VSAM03 333 OD R/W - OS 
SYS109 190 Ss R/0 
SYS19E 19E Y/S R/O 


Use the volume label VSAM03 in the MASTCAT AMSERV file: 


DEFINE MASTERCATALOG - 
(NAME (MASTCAT ) - 
VOLUME (VSAMO3) - 
CYL (4) - 

FILE (IJSYSCT) ) 


To find out what extents on this minidisk you can allocate for VSAM, 
use the LISTDS command with the FREE option: 


listds d (free 
The response from LISTDS might look like this: 


FREESPACE INFORMATION FOR '"D* DISK: 
CYL-HD (RELTRK) TO CYL-HD (RELTRK) TRACKS 
000 01 1 000 09 9 9 
000 11 11 029 18 569 560 


From this response, you can see that the VTOC is located on the first 
cylinder, so you can allocate cylinders 1 through 29 for VSAM: 


dlbl ijsysct d dsn mastcat (perm extent 
DMSDLB331R ENTER EXTENT SPECIFICATIONS: 
19 551 

(null line) 


After entering the extents, in tracks, giving the relative track number 
of the first track to be allocated followed by the number of tracks, you 
must enter a null line to complete the command. (A null line is required 
because, when you enter multiple extents, entries may be placed on more 
than one line.) 


Now you can issue the AMSERV command: 
anuserv mastcat 
A ready message with no return code indicates that the master catalog is 


defined. You do not need to reissue the DLBL command in order to 
identify the master catalog for additional AMSERV functions. 


Defining User Catalogs 


You can use the AMSERV command to define private catalogs and spaces for 
them. The procedures for determining what space you can allocate are the 
same as those outlined in the example of defining a master catalog. 
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To define a user catalog, you can assign any ddname you want: 


access 199 e 
listds e (free 


dlbl cat1 e dsn private.catl (extent 


amserv usercat 
The file USERCAT AMSERV might contain the following: 


DEFINE USERCATALOG - 
(NAME (PRIVATE.CAT1) - 
FILE (CAT1) - 
CYL (4) - 
VOLUME (OSVSAM) - 
CATALOG (MASTCAT) 


After this AMSERV command has completed successfully you can use the 
catalog PRIVATE.CAT1. When you define a file cataloged init, you 
identify it using the CAT option on the DLBL command: 


dlbl file2 e dsn ? (cat cat! 


Or, you can define it as a job catalog. 


Using a Job Catalog 


During a terminal session, you may be referencing the same private 
catalog many times. If this is the case, you can identify a job catalog 
by using the ddname IJSYSUC. Then, that catalog is searched during all 
subsequent jobs, unless you override it using the CAT option when you 
use the DLBL command to define a file. 


If you defined a user catalog (IJSYSUC) for a terminal session and 
you use the AMSERV command to access a VSAM file, the user catalog takes 
precedence over the master catalog. This means that for files that 
already exist, the job catalog is searched. When you define a cluster, 
it is cataloged in the job catalog, rather than in the master catalog, 
unless you use the CAT option to override it. CMS never searches nore 
than one VSAM catalog. 


You should use the CAT option to name a catalog when the AMSERV file 


you are executing references, with the CATALOG parameter, a cataiog that 
is not defined either as the master catalog or asS a user catalog. 
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If you want to use additional catalogs during a terminal session, you 
first define them just as you would any other VSAM file: 


dlbl mycat2 f£ dsn private.cat2 (vsanm 


Then, when you enter the DLBL command for the VSAM file that is 
cataloged in PRIVATE.CAT2 use the CAT option to refer to the ddname of 
the catalog: 


dlbl input f dsn input.file (cat mycat2 


If you want to stop using a job catalog defined with the ddname IJSYSUC, 
you can clear it using the CLEAR option of the DLBL command: 


dlbl ijsysuc clear 


or, you can assign the ddname IJSYSUC to some other catalog. If you 
clear the ddname for IJSYSUC, then the master catalog becomes’ the job 
catalog. 


Catalog Passwords 


When you define passwords for VSAM catalogs in CMS, or when you use CMS 
to access VSAM catalogs that have passwords associated with them, you 
must supply the password from your terminal when the AMSERV command 
executes. The message that you receive to prompt you for the password 
is the same message you receive when you execute access method services: 


4221A ATTEMPT 1 OF 2. ENTER PASSWORD FOR JOB AMSERV FILE catalog 


When you enter the proper password, AMSERV continues execution. 


DEFINING AND ALLOCATING SPACE FOR VSAM FILES 


You can use CMS AMSERV to allocate additional data spaces for VSAM. To 
use the DEFINE SPACE control statement, you must have defined either the 
master catalog or a user catalog which will control the space, and you 
must have the volume or volumes on which the space is to be allocated 
mounted and accessed. 


For example, suppose you have an OS 3330 disk attached to your 
virtual machine at virtual address 255. After accessing the disk and 
determining the free space on it, you could create a file named SPACE 
AMSERV: 


DEFINE SPACE - 
(FILE (FILE1) - 
TRACKS (1900) - 
VOLUME (123456) - 
CATALOG (PRIVATE.CAT2 CAT2) ) 


To execute this AMSERV file, you must define PRIVATE.CAT2 using the 
ddname CAT2, and then define the ddname for the file: 


access 255 c 

dlbl cat2 c dsn private.cat2 (vsam 

dlbl filel c (extent cat cat2 
You do not need to enter a data set name to define the space. When CMS 
prompts you for the extents of the space, you can enter the extent 
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specifications: 


DMSDLB331R ENTER EXTENT SPECIFICATIONS: 
190 1900 


When you define space for VSAM, you should be sure that the VOLUMES 
parameter and the space allocation parameter (whether CYLINDER, TRACKS, 
BLOCKS, or RECORDS) in the AMSERV file agree with the track information 
you provide in the DLBL command. 


Specifying Multiple Extents 


When you are specifying extents for a master catalog, data space, or 
unigue file, you can specify up to 16 extentS on a volume for a 
particular space. When prompted by CMS for the extents, you must 
separate the different extents by commas, or place them on different 
lines. To specify a range of extents in the above example, you could 
enter: 


dlbl filel c (extent 
190 190, 570 190, 1900 1520 
(null line) 


dlbl file1l c (extent 


190 190 
570 190 
1900 1520 


(null line) 


Again, the first number entered for each extent represents the relative 
track for the beginning of the extent and the second number indicates 
the number of tracks. 


Specifying Multivolume Extents 


You can define spaces that span up to nine volumes for VSAM files; all 
of the volumes must be accessed and assigned when you issue the DLBL 
command to define or identify the data space. 


You should remember, though, that if you are using AMSERV and you do 
not use the PRINT option, you must have a read/write CMS disk so that 
AMSERV can write the output LISTING file. 


If you are defining a new mnultivolume data space or unique cluster, 
you must specify the extents on each volume that the data is to occupy 
(starting track and number of tracks), followed by the disk node letter 
at which the disk is assigned: 
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access 135 b 
access 136 c 
access 137 d 
dlbl newfile b (extent 
DMSDLB331R ENTER EXTENT SPECIFICATIONS: 
100 60 b, 400 80 b, 60 4O d, 
2000 100 c 
(null line) 


If you enter more than one extent on the same line, the extents must be 
separated by commas; if you enter a comma at the end of a line, it is 
ignored. Different extents for the same volume must be _ entered 
consecutively. Note that in this example, the extent information is for 
2314 disks and that these extents are also on cylinder boundaries. 


When you enter multivolume extents, you do not have to enter a node 
letter for those extents on the disk identified in the DLBL command. 
For the extents on disk B in the above example, you could enter: 


dlbl newfile b (extent 
DMSDLB331R ENTER EXTENT SPECIFICATIONS: 
100 400 80, 60, 60 40 d 
2000 100 c 
(null line) 


If you make any errors issuing the DLBL command or extent 
information, you must reissue the entire command sequence. 


IDENTIFYING EXISTING MULTIVCLUME FILES: When you issue a DLBL command to 
identify an existing multivolume VSAM file, you must use the MULT option 
of the DLBL command sequence: 


dlbl old bi1dsn ? (nult 
DMSDLB220R ENTER DATASET NAME: 
vsantest. file 
DMSDLB330R ENTER VOLUME SPECIFICATIONS: 
c, d 
e 

(null line) 


When you enter the DLBL command you should specify the mode letter for 
the first disk volume on the command line. When you enter the MULT 
option you are prompted to enter additional specifications for the 
remaining extents. In the above example, the data set has extents on 
disks accessed as B-, C-, D-, and E-disks. 


USING TAPE INPUT AND OUTPUT 


If you are using AMSERV for a function that requires tape input and/or 
output, you must have the tape(s) attached to your virtual machine. The 
valid addresses for tapes are 181, 182, 183, and 184. When referring to 
tapes, you can also refer to them using their CMS symbolic names TAP1, 
TAP2, TAP3, and TAP4&. 


When you use AMSERV to create or read a tape, you supply the ddname 
for the tape device interactively, after you issue the AMSERV command. 
To indicate to AMSERV that you are using tare for input or output, you 
must use the TAPIN or TAPOUT option to specify the tape device being 
used: 
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labeldef tapedd fid filename... 
amservy export (tapout 181 


In this example, the output from an EXPORT function is toa tape at 
virtual address 181. CMS prompts you to enter the ddname: 


DMSAMS367R ENTER TAPE OUTPUT DDNAMES:; 


After you enter the ddname (TAPEDD in this example) for the tape file, 
AMSERV begins execution. 


AMSERV in CMS assumes that tape volumes used for input and/or output 
have IBM standard tape labels, i.e., VOL1, HDR1, etc. The user can 
override this default by indicating to AMSERV via Access Method Services 
control statements to use non label tapes. If standard label tapes are 
used the LABELDEF command is required. The CMS/DOS routine that 
performs the tape open needs label information for standard label tapes. 
See the description of the LABELDEF command in Section 7 for further 
information. The filename you specify on the LABELDEF command should be 
the same one you use to reply to the access method service message that 
requested you to supply the tape's ddnames. However, the LABELDEF 
command must be issued before the AMSERV command. If you only want the 
tape labels skipped, but not checked, enter a LABELDEF with no 
parameters other than filename. 


Standard label tapes used for input must always contain standard 
VOL1, HDR1, and EOF1 labels or they are rejected by CMS AMSERV. 
Standard label output tapes do not need to contain VOL1 labels because 
the user is prompted to enter a volume serial number and have the VOL1 
label written if he wants. However, blank tapes should not be used for 
output because the open routine tries to read the tape. 


Reading Tapes 


When you create a tape file using AMSERV under CMS, CMS writes a mark 
preceding each output file. When CMS AMSERV is used to read this same 
file, it automatically skips past the tape mark to read the file. If 
you want to read the tape on a real OS/VS system, however, you must use 
the LABEL=SL as a parameter on the data definition (DD) card for the 
tape. When you create a tape file using AMSERV under CMS, CMS writes a 
label file preceding each output file. When CMS AMSERV is used to read 
this same file, it checks the HDR1 and VOL1 labels using the LABELDEF 
command you provide before it reads the data file. If you want to read 
the tape on a real OS/VS system, however, you must use the LABEL=SL as a 
parameter on the data definition (DD) card for the tape. If you want to 
read the tape on areal OS/VS system, however, you must use either 
LABEL=SL or LABEL=(2,NL) aS a parameter on the data definition (DD) card 
for the tape. 


If you are creating a tape under OS/VS access method services to be 
read by CMS AMSERV, you must be sure to create the tape using standard 
labels so that CMS can read it properly. CMS will not be able to read a 
tape created with LABEL=(,NL) on the DD card. 


For CMS to read this tape for any other purpose (for example, to use 
the MOVEFILE command to copy it), you must remember to forward space the 
file past the tape mark before beginning to read it. 
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Using AMSERV Under CMS 


This section provides examples of AMSERV functions executed under CMS. 
The examples are applicable to both the CMS (OS) and CMS/DOS 
environments. You should be familiar with the material presented in 
either "Defining DOS Input and Output Files" or "Defining OS Input and 
Output Files," depending on whether you are a DOS or anoOS_ user, 
respectively. For the examples shown below, command lines and options 
that are required only for CMS/DOS users are shaded. OS users should 
ignore these shaded entries. 


A CMS format variable file cannot be used directly as input to AMSERV 
functions as a variable (V) or variable blocked (VB) file because the 
Standard variable CMS record does not contain the BL and RL headers 
needed by the variable record modules. If these headers are not included 
in the record, errors will result. 


All files placed on the CMS disk by AMSERV will show a_ RECFM of V, 
even if the true format is fixed (F), fixed blocked (FB), undefined (U), 
variable or variable blocked. The programmer must know the true format 
of the file he is trying to use with the AMSERV command and access it 
properly or errors will result. 


A CMS standard variabie-format file can be accessed as RECFM=U to use 
the file as follows: 


AMSERV AMREPUV 
The file AMREPUV AMSERV contains the following 2 cards: 


REPRO INFILE (INPUT ENV (RECFM (U) ,BLKSZ (800) , PDEV (3330))) 
OUTFILE (OUTPUT ENV (RECFM (V) , BLKSZ (800) , RECSZ (84) , PDEV (3330))) 


The input file can be any CMS file with LRECL 800 or less. The 
output file will be a true variable file that can be used with AMSERV. 


USING THE DEFINE AND DELETE FUNCTIONS 


When you use the DEFINE and DELETE control statements of AMSERV, you do 
not need to specify the DSN parameter on the DLBL command: 


If the above commands are executed prior to an AMSERV command to define 
a master catalog, the DEFINE will be successful as long as_ you have 
assigned a data set name uSing the NAME parameter in the AMSERV file. 
The same is true when you define clusters, or when you use the DELETE 
function to delete a cluster, space, or catalog. 


When you do not specify a data set name, AMSERV obtains the name fron 
the AMSERV file. In the case of defining or deleting space, no data set 
hame is needed; the FILE parameter corresponding to the ddname is all 
that is necessary, and AMSERV assigns a default data set name to the 
space. 


When you define space on a minidisk using AMSERV, CMS does not check 
the extents you specify to see whether they are greater than the number 
of cylinders available. As long as the starting cylinder is a valid 
cylinder number and the extents you specify are on cylinder boundaries, 
the DEFINE function completes successfully. However, you receive an 
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error message when you use an AMSERV function that tries to use this 
space. 


Defining a Suballocated Cluster 


To define a cluster for VSAM space that has already been allocated, you 
need (1) an AMSERV file containing the control statements necessary for 
defining the cluster, and (2) the master catalog (and, perhaps, user 
catalog) volume, which will point to the cluster. The volume on which 
the cluster is to reside does not have to be online when you define a 
suballocated cluster. 


For example, the file CLUSTER AMSERV contains the following: 


DEFINE CLUSTER ( NAME (BOOK.LIST) - 
VOLUMES (123456) - 
TRACKS (40) - 
KEYS (14,0) RECORDSIZE (120,132) ) - 
DATA (NAME (BOOK.LIST. DATA) ) - 
INDEX (NAME (BOOK.LIST.INDEX) ) 


To execute this file, you would need to enter the following command 
sequence (assuming that the master catalog, on volume 123456, is in your 
virtual machine at address 310): 


access 310 b 


dibl ijsysct b (perm @¥#Gat 
amserv cluster 


Defining a Unique Cluster 


For a unigue cluster (one defined with the UNIQUE attribute), you must 
define the space for the cluster at the same time you define its name 
and attributes; thus the volume or volumes on which the cluster is to 
reside must be mounted and accessed when you execute the AMSERV command. 
You can supply extent information for the cluster's data and index 
portions separately. 


To execute an AMSERV file named UNIQUE which contains the following 
(the ellipses indicate that the AMSERV file is not complete): 


DEFINE CLUSTER - 

(NAME (PAYROLL) ) - 

DATA ( FILE (UDATA) - 
UNIQUE - 
VOLUMES (567890) — 
CYLINDERS (40) - 
<x f= 

INDEX ( FILE (UINDEX) ) - 
UNIQUE - 
VOLUMES (567890) - 
CYLINDERS (10) - 


cee ) 
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the command sequence should be: 


access 350 —_ 


‘aesgn SgsG08 c 
dlbl udata c (extent @yeoow 
DNSDLB331R eeeeen EXTENT SPECIFICATIONS: 


amserv unique 


Deleting Clusters, Spaces, and Catalogs 


When you use AMSERV to delete a VSAM cluster, the volume containing the 
cluster does not have to be accessed unless the volume also contains the 
catalog in which the cluster is defined. In the case of data spaces and 
user catalogs or the master catalog, however, the volume(s) must be 
mounted and accessed in order to delete the space. 


When you delete a cluster or a catalog, you do not need _ to use the 
DLBL command, except to define the master catalog; AMSERV can obtain the 
necessary file information from the AMSERV file. 


You should be particularly careful when you are using temporary disks 
with AMSERV, that you have not cataloged a temporary data space or 
cluster in a permanent catalog. You will not be able to delete the space 
or cluster from the catalog. 


USING THE REPRO, IMPORT, AND EXPORT (OR EXPORTRA/IMPORTRA) FUNCTIONS 


You can manipulate VSAM files in CMS with the REPRO, IMPORT, and EXPORT 
functions of AMSERV. You can create VSAM files from sequential tape or 
disk files (on OS, DOS, or CMS disks) using the REPRO function. Using 
REPRO, you can also copy VSAM files into CMS disk files or onto tapes. 
For the IMPORT/EXPORT process, you have the option (for smaller files) 
of exporting VSAM files to CMS disks, as well as to tapes. 


You cannot, however, use the EXPORT function to write files onto OS 
or DOS disks. Nor can you use the REPRO function to copy ISAM (indexed 
sequential) files into VSAM data sets, since CMS cannot read ISAM files. 


When creating a VSAM file from a non-VSAM disk file, the device track 
size must be the maximum BLOCKSIZE in the INFILE statement. AMSERV 
expects a DOS or OS file as input and will not open a disk file when the 
BLOCKSIZE specified is greater than the track capacity of the disk 
device being used. 


You cannot use the ERASE or PURGE options of the EXPORT command if 
you are exporting a VSAM file from a read-only disk. The export 
operation succeeds, but the listing indicates an error code 184, meaning 
that the erase function could nct be performed. 


You should not use an EXPORT DISCONNECT function from a CMS minidisk 
and try to perform an IMPORT CONNECT function for that data set onto an 
OS systen. OS incorrectly rebuilds the data set control block (DSCB) 
that indicates how much space is available. 


Section 10. Using Access Method Services and VSAM 233 


The AMSERV file below gives an example of using the REPRO function to 
copy a CMS sequential file into a VSAM file. The CMS input file must be 
sorted in alphameric sequence before it can be copied into the VSAM 
file, which is a keyed sequential data set (KSDS). The VSAM cluster, 
NAME.LIST, is defined in an AMSERV file named PAYROLL: 


DEFINE CLUSTER ( NAME (NAME.LIST ) - 
VOLUMES (CMSDEV) - 
TRACKS (20) - 
KEYS (14,0) - 
RECORDSIZE (120,132) ) - 
DATA (NAME (NAME.LIST.DATA) ) - 
INDEX (NAME (NAME.LIST.INDEX ) ) 


To sort the CMS file, create the cluster and copy the CMS file into 
it, use the following commands: 


sort name list a name sort a 
DMSSRT604R ENTER SORT FIELDS: 
1 #14 

ocho 135 Cc 


dibl name c dsn name list (#¥@007 
amserv repro 


The file REPRO AMSERV contains: 


REPRO INFILE ( SORT - 
ENV (RECORDFORMAT (F) - 
BLOCKSIZE (80) - 
PDEV (3330) )) - 
OUTFILE (NAME) 


When you use the REPRO, IMPORT, or EXPORT functions with tape files, 
you must remember to use the TAPIN and TAPOUT options of the AMSERV 
command. These options perform two functions: they allow you to specify 
the device address of the tape, and they notify AMSERV to prompt you to 
enter a ddname. 


In the example below, a VSAM file is being exported to a tape. The 
file, TEXPORT AMSERV, contains: 


EXPORT NAME.LIST - 
INFILE (NAME) - 
OUTFILE (TAPE ENV (PDEV (2400) ) ) 


To execute this AMSERV, you enter the commands as follows: 


(s¥8006 vsan 
amserv texport (tapout 181 

DMSAMS367R ENTER TAPE OUTPUT DDNAMES: 
tape 


The fid, volid, and exdte parameters on LABFLDEF are only examples; 
you can substitute any value you want for them on your tape label. 
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WRITING EXECS FOR AMSERV AND VSAM 


You may find it convenient to use EXEC procedures for most of your 
AMSERV functions, as well as setting up input and output files for 
program execution, and executing your VSAM programs. If, for example, a 
particular AMSERV function requires several disks and a number of DLBL 
statements, you can place all of the required commands in an EXEC file. 
For example, if the file below is named SETUP EXEC: 


ACCESS 135 B 
ACCESS 136 C 
ACCESS 137 D 
ACCESS 300 G 
-ASSG sca 


AMSERV MULTFILE 


to invoke this sequence of commands, all you have to enter is the name 
of the EXEC: 


setup 


If you place, at the beginning of the EXEC file, the EXEC control 
statement: 


S&ERROR GEXIT &RETCODE 


then, you can be sure that the AMSERV command does not execute unless 
all of the prior commands completed successfully. 


For those AMSERV functions that issue response messages, you can use 
the &STACK EXEC control statement. For example: 


GERROR S&EXIT GRETCODE 
ACCESS 305 D 


LABELDEF TAPE FID FILE1 

SERROR &CONTINUE 

ESTACK TAPE 

AMSERV TIMPORT (TAPIN 181 

SIF SRETCODE NE 0 TYPE TIMPORT LISTING 
TAPE REW 

GEXIT 0 


When the AMSERV command in the EXEC is executed, the request for the 
tape ddname is satisfied immediately, by the response stacked with the 
ESTACK statement. 


If you are executing a command that accepts multiple response lines, 
you have to stack a null line as follows: 


ESTACK C S¥SO1 
& STACK 7 
DLBL MULTFILE B (MULT S¥S001 


2, D SsYso0? 


Note: You can use the &BEGSTACK control statement to stack a series of 
responses in an EXEC, but you must use &STACK to stack a null line. 
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Section 11. How VM/SP Can Help You Debug Your Programs 


Debugging is a critical part of the program development process. When 
you encounter problems executing application programs or when you want 
to test new lines of code, you can use a variety of CP and CMS debugging 
commands and techniques to examine your program while it is executing. 


You can interrupt the execution of a program to examine and change 
your general registers, storage areas, or control words such as’ the 
program status word (PSW), and then continue execution. Also, you can 
trace the execution of a program closely, so you can see where branches 
are being taken and when supervisor calls or I/O interruptions occur. 


In many cases, you May never need to look at a dump of a program to 
identify a problen. 


Preparing to Debug 


Before beginning to debug a program, you should have a current program 
listing for reference. When you use VM/SP to debug a program, you can 
monitor program execution, instruction by instruction, so you must have 
an accurate list of instruction addresses and addresses of program 
storage areas. You can obtain a listing of your program by using the 
PRINT command to print the LISTING file created by the assembler or 
compiler. To determine the virtual storage locations of program entry 
points, use the LOAD MAP file created by the LOAD and INCLUDE commands. 
If you are a CMS/DOS user, use the linkage editor map produced by the 
DOSLKED command. 


If the program that you are debugging creates printed or punched 
output and you will be executing the program repeatedly, you may not 
wish all of the output printed or punched. You should place your 
printer or punch in a hold status, so that any files spooled to these 
devices are not released until you specifically request it: 


cp spool printer hold 
cp spool punch hold 


When you are finished debugging you can use the CP QUERY command to see 
what files are being held and then you can select which files you may 
want to purge or release. 


When a Program Abends 


The most common problem you might encounter is an abnormal termination 
resulting from a program interruption. When a program running in a CMS 
Virtual machine abnormally terminates (abends), you receive, at your 
terminal, the message: 


DMSITP141T exception EXCEPTION OCCURRED AT address IN ROUTINE name 
and your virtual machine is returned to the CMS environment. From the 
message you can determine the type of exception (program check, 


operation, specification, and so on), and, often, the instruction 
address in your program at which the error occurred. 
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Sometimes this is enough information for you to correct the error in. 


your source program, recompile it and attempt to execute it again. 


When this information does not immediately identify the problem in 
your program, you can begin debugging procedures using VM/SP. To access 
your program's storage areas and registers you can enter the command: 


debug 


immediately after receiving the abend message. This command places your 
virtual machine in the debug environment. 


To check the contents of general registers 0 through 15, issue the 
DEBUG subcommand: 


gpr 0 15 


If you want to look at only one register, enter: 


gpr 3 


You might also wish to check the program status word (PSW). Use the PSW 
subcommand: 


psw 
You can examine storage areas in your program using the X subcommand: 
X 201AC 20 


In this example, the subcommand requests a display of 20 bytes, 
beginning at location 201AC in your program. User programs executed in 
CMS are always loaded beginning at location X'20000' unless you specify 
a different address on the LOAD or FETCH command. To identify the 
virtual address of any instruction ina program, you only need to add 
20000 to the hexadecimal instruction address. 


RESUMING EXECUTION AFTER A PROGRAM CHECK 


On occasion, you will be able to determine the cause of a program check 
and continue the execution of your program. There are DEBUG subcommands 
you can use to alter your program while it is in storage and resune 
execution. 


If, for example, the error occurred because you had forgotten to 
initialize a register to contain a zero, you could use the DEBUG 
subcommand SET to place a zero in the register, and then resume 
execution with the GO subcommand. You can use the GO subcommand to 
specify the instruction address at which you want execution to begin: 


set gpr 11 0000 
go 20080 


An alternate method of specifying a starting address at which execution 
is to resume is by using the SET subcommand to change the last word of 
the PSW: 


set psw Q 00020080 
go 
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If your program executes successfully, you can then make _ the 
necessary changes to your source file, recompile, and continue testing. 


Using DEBUG Subcommands to Monitor Program Execution 


The preceding examples did not represent a _ wide range of the 
possibilities for DEBUG subcommands. Nor do they represent the only way 
to approach program debugging. Some additional DEBUG subcommands are 
illustrated below. For complete details in using these subconmmands, 
refer to the VMN/SP CMS Command and Macro Reference. 


When you prepare to debug a program with known problems, or when you 
are beginning to debug a program for the first time, you might want to 
stop program execution at various instructions and examine the 
registers, constants, buffers, and so on. To temporarily stop progran 
execution, use the BREAK subcommand to set breakpoints. You should set 
breakpoints after you load the program into storage, but before _ you 
begin executing it. You can set up to 16 breakpoints at one time. For 
each breakpoint, you assign a value (id), and an instruction address: 


load myprog 
debug 

break 0 20BCO 
break 1 20C10 
break 2 20D00 


Then, you can return to CMS and begin execution: 


return 
start 


When the first breakpoint in this example is encountered, you receive 
the messages: 


DEBUG ENTERED. 
BREAKPOINT O AT 20BCO 


Then, in the debug environment, use the subcommands GPR, CSW, CAW, PSH, 
and X to display registers, control words, or storage locations. 


You can resume program execution with the GO subcommand: 
go 
If, at any time, you decide that you do not want to finish executing 
your program, but want to return to the CMS environment immediately, you 
must use the HX subcommand: 


hx 


There are three subcommands you can use to exit from the debug 
environment: 


1. RETURN, to return to the CMS environment when DEBUG is entered with 
the DEBUG command 


2. GO, to resume program execution when it has been interrupted by a 
breakpoint 


3. HX, to halt program execution entirely and return to the CMS 
environment 
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If you try to leave the debug environment with the wrong subcommand 
you receive the message: 


INCORRECT DEBUG EXIT 


and you have to enter the proper subcommand. 


USING SYMBOLS WITH DEBUG 


To simplify the process of debugging in the CMS debug environment, you 
can use the ORIGIN and DEFINE sukcommands. The ORIGIN command allows 
you to set an instruction location to serve as the base for all the 
addresses you specify. For example, if you specify: 


origin 20000 


then, to refer to your virtual storage location 201BC, you only need to 
enter: 


x tbe 


By setting the DEBUG origin at your program's base address, you can 
refer to locations in your program by the virtual storage numbers in the 
listing, rather than having to compute the actual virtual storage 
address each time. The current DEBUG origin stays in effect until you 
set it to a different value or until you reload CMS (with the IPL 
command). 


You can use the DEFINE subcommand to assign symbolic names to storage 
locations so that you can reference those locations by symbol, rather 
than by storage address. For example, suppose that during a DEBUG 
session you will repeatedly be examining three particular storage 
locations labeled in your program NAME1, NAME2, and NAME3. They are at 
locations 20EF0O, 20EFA, and 20FO4. Enter: 


load nameprog 

debug 

origin 20000 

define name? EFO 10 
define name2 EFA 10 
define name3 FO4 10 
break 1 a04 

return 

start 


When the specified breakpoint is encountered, you can examine these 
storage areas by entering: 


xX hamet 
xX name2 
xX name3 


You can also refer to these symbols by name when you use the STORE 
subconmmand: 


store name2 c4c5Sc3c5Scle#e5d6c9d9 


The names you specify do not have to be the same as the labels in the 
program; you can define any name up to eight characters. 


Figure 20 summarizes the DEBUG subcommands. 
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Subcommand Format | Function 


BReak id Viderecr |Stops program execution at the 
hexloc | specified breakpoint. 


CAW [Displays the contents of the 
|channel address word. 


CSW {Displays the contents of the 
|channel status word. 


r , |ASSigns a symbolic name to the 
DEFine symbol hexloc |bytecount| |virtual storage address. 
| 4 | | 


L J | 


|Dumps the contents of specified 


r i m | 1 
DUmp |symboll |symbol2| [ident] | | virtual storage locations to the 
{[hexloc1 | hexloc2| { | virtual spooled printer. 
i Q i * | 1 | 
L tL 32 4 4 | 
c 1 | Returns control to your progran 
GO |symbol| [and starts execution at the 
|hexloc| | specified location. 
L Jj | 
GPR reg1 [reg2 ] | Displays the contents of the 
[specified general registers. 
HX |Halts execution and returns to 
[the CMS command environment. 
r 1 | Specifies the base address to be 
ORigin |symbol| jadded to locations specified in 
|hexloc| {other DEBUG subcommands. 
| oO | | 
L J | 
PSW |Cisplays the contents of the old 
| program status word. 
RETurn [Exits from debug environment to 
|the CMS command environment. 
SET (CAW hexinfo [Changes the contents of specified 
CSW hexinfo [hexinfo] [control words or registers. 


PSW hexinfo [ hexinfo] I 
GPR reg hexinfo [ hexinfo] | 


STore teats hexinfo [hexinfo] |Stores up to 12 bytes of informa— 
hexloc | tion starting at the specified 
[virtual storage location. 


| Examines virtual storage 


— a ot EP eee eee ogee ee eo eee ee eee eee eee ee eee ee eo ee ee ees ee eee ea ee ee eee aie eee ee eae ee oe ee ee eae ee oe eee eee ees eee ee 
—eemmo ees eee oe ee 2 oe eee eee oe ee oe ee ee ee eee ee ee ee ee ee ee eo ee ee ee eae ae ees eae eee eee ee ees aes es es esis aes aes sae ee ee ee eee eee es eases eee ee oe 


| 7 
X [symbol | on | {| locations. 

[length | | 
L J | 
r 1 { 

hexloc |n | | 
14 | { 
L J | 


Figure 20. Summary of DEBUG Sukcommands 
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What To Do When Your Program Loops 


If, when your program is executing, it seems to be in a loop, you should 
first verify that it is looping, and then interrupt its execution and 
either (1) halt it entirely and return to the CMS environment or (2) 
resume its execution at an address outside of the loop. 


The first indication of a program loop may be either what seems to be 
an unreasonably long processing time, or, if you have a blip character 
defined, an inordinately large number of blips. 


You can verify a loop by checking the PSW frequently. If the last 
word repeatedly contains the same address, it is a fairly good 
indication that your program is ina loop. You can check the PSW by 
uSing the Attention key to enter the CP environment. You are notified 
by the message: 


CP 


that your virtual machine is in the CP environment. You can then use 
the CP command DISPLAY to examine the PSW: 


cp display psw 
and then enter the command BEGIN to resume program execution: 
cp begin 


If you are checking for a loop, you might enter both commands on the 
same line using the logical line end: 


cp d p#b 


When you have determined that your program is ina loop, you can halt 
execution using the CMS Immediate command HX. To enter this command, 
you must press the Attention key once to interrupt program execution, 
then enter: 


hx 


If you want your program to continue executing at an address past the 
loop, you can use the CP command BEGIN to specify the address at which 
you want to continue execution: 


cp begin 20cd0 


Or, you could use the CP command STORE to change the instruction address 
in the PSW before entering the BEGIN command: 


cp store psw 0 20cd0#begin 


Tracing Program Activity 


When your program iS in a loop, or when you have a program that takes an 
unexpected branch, you might need to trace the execution closely to 
determine at what instruction the program goes astray. There are two 
commands you can use to do this. The SVCTRACE command is a CMS command 
which traces all SVCs (supervisor calls) in your progran. The TRACE 
command is a CP command which allows you’ to trace different kinds of 
information, including supervisor call instructions. 
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USING THE CP TRACE COMMAND 


You can trace the following kinds of activity in a program using the CP 
TRACE command: 


Instructions 

Branches 

Interrupts (including program, external, I/O and SVC interrupts) 
I/O and channel activity 


When the TRACE command executes, it traces all your virtual machine's 
activity; when your program issues a supervisor call, or calls any CMS 
routine, the TRACE continues. 


You can make most efficient use of the TRACE command by starting the 
trace at a specific instruction location. You should set an address 
stop for the location. For example, if you are going to execute a 
program and you want to trace all of the branches made, you would enter 
the following sequence of commands to begin executing the program and 
Start the trace: 


load progress 
cp adstop 20004 
start 

ADSTOP AT 20004 
cp trace branch 
cp begin 


Now, whenever your program executes a branch instruction, you receive 
information at the terminal that might look like this: 


0O2001E BALR O5E6 ==> 020092 
This line indicates that the instruction at address 2001E resulted ina 
branch to the address 020092. When this information is displayed, your 
virtual machine is placed in the CP environment, and you must’ use the 
BEGIN command to continue execution: 

cp begin 


When you locate the branch that caused the problem in your progran, 
you should terminate tracing activity by entering: 


cp trace end 
and then you can use CP commands’ to continue debugging or you can use 
the EXTERNAL command to cause an external interruption that places your 
virtual machine in the debug environment: 

cp external 


You receive the message: 


DEBUG ENTERED. 
EXTERNAL INTERRUPT 


And you can use the DEBUG subcommands to investigate the status of your 
progran. 
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Controlling a CP Trace 


There are several things you can do to control the amount of information 
you receive when you are using the TRACE command, and how it is 
received. For example, if you do not want program execution to halt 
every time a trace output message is issued, you can use the RUN option: 


cp trace svc run 
Then, you can halt execution by pressing the Attention key when the 
interruption you are waiting for occurs. You should use this option if 
you do not want to halt execution at all, but merely want to watch what 
is happening in your progran. 
Similarly, if you do not require your trace output immediately, you 


can specify that it be directed to the printer, so that your terminal 
does not receive any information at all: 


cp trace inst printer 
When you direct trace output to a fprinter, the trace output is mixed in 
with any printed program output. If you want trace output separated 
from other printed output, use the CP DEFINE command to define a second 
printer at a virtual address lower than that of your printer at OOE. For 
example: 

cp define printer 006 


Then, trace output will be in a separate spool file. CMS printed output 
always goes to the printer at address O0E. 


When you finish tracing, use the CP CLOSE command to close the 
virtual printer file: 


cp close e 
cp close 006 


If you want trace output at the printer and at the terminal, you can use 
the BOTH option: 


cp trace all both 


Suspending Tracing 


If you are debugging a program that does a lot of I/O, or that issues 
many SVCs, and you are tracing instructions or branches, you might not 
wish to have tracing in effect when the supervisor or I/O routine has 
control. When you notice that addresses being traced are not in your 
program, you can enter: 


cp trace end 


and then set an address stop at the location in your program that 
receives control when the supervisor or I/O routine has completed: 


cp adstop 20688 
begin 
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Then, when this address is encountered, you can re-enter the CP TRACE 
command. 


USING THE SVCTRACE COMMAND 


If your program issues many SVCs, you may not get all of the information 
you need uSing the CP TRACE command. The SVCTRACE command is a CMS 
command, which provides more detailed information about all SVCs in your 
program, including register contents before and after the SVC, the name 
of the called routine, and the location from which it was called, and 
the contents of the parameter list passed to the SVC. 


The SVCTRACE command has only two operands, ON and OFF, to begin and 
end tracing. SVCTRACE information can be directed only to the printer, 
so you do not receive trace information at the terminal. 


Since the SVCTRACE command can only be entered from the CMS 
environment, you must use the Immediate commands SO (suspend tracing) or 
HO (halt tracing) if you want tracing to stop while a program is 
executing. Use the Immediate conmand RO to resume tracing. 


Since the CMS system is "SVC-driven", this debugging technigue can be 
useful, especially, when you are debugging CMS programs. For more 
information on writing programs to execute in CMS, see "Section 13. 
Programming for the CMS Environment." 


Using CP Debugging Commands 


In addition to the CMS debugging facilities, there are CP commands that 
you can use to debug your programs. These commands are: 


e DISPLAY, which you can use to examine virtual storage, registers, or 
control words, like the PSW 


® ADSTOP, which you can use to set an instruction address stop in your 
program 


©® STORE, which you can use to change the contents of a_ storage 
location, register, or control word 


When you use the display command, you can request an EBCDIC 
translation of the display by prefacing the location you want displayed 
with a "T"; 


cp display t20000.10 
This command requests a display of xX'10" (16) bytes beginning at 
location X¥'20000'. The display is formatted four words to a line, with 
EBCDIC translation at the left, much as you would see it in a dump. 


You can also use the DISPLAY command to examine the general 
registers. For example, the commands: 


cp display g 

cp display g1 

cp display g2-5 
result in displays of all the general registers, of general register 1, 
and of a range of registers 2 through 5. 
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The DISPLAY command also displays the PSW, CAW, and CSW: 


cp display psw 
cp display caw 
cp display csv 


With the STORE command, you can change the contents’ of registers, 
storage areas, or the PSW. 


As you can see, the CMS DEBUG subcommands and the CP commands ADSTOP, 
DISPLAY, and STORE, have many duplicate functions. The environment you 
choose to work in, CP or debug, is a matter of personal preference. The 
differences are summarized in Figure 21. What you should be aware of, 
however, is that you should never attempt to use a combination of CP 
commands and DEBUG subcommands when you are debugging a program. Since 
DEBUG itself is a program, when it is running (that is, when you are in 
the debug environment), the registers that CP recognizes as your virtual 
machine's registers are actually the registers being used by DEBUG. 
DEBUG saves your program's registers and PSW and keeps them in a special 
save area. Therefore, if you enter the DEBUG and CP commands to display 
registers, you will see that the register contents are different: 


gpr 0 15 
#cp dg 


DEBUGGING WITH CP AFTER A PROGRAM CHECK 


When a program that is executing under CMS abends because of a program 
check, the DEBUG routine is in control and saveS your program's 
registers, so that if you want to begin debugging, you must’ use the 
DEBUG command to enter the debug environment. 


You can prevent DEBUG from gaining control when a program 
interruption occurs by setting the wait bit in the program new PSW: 


cp trace prog norun 


You should do this before you begin executing your program. Then, if a 
program check occurs during execution, when CP tries to load the progran 
new PSW, the wait Lit forces CP into a disabled wait state and you 
receive the message: 


DMKDSP450W CP ENTERED; DISABLED WAIT PSW 


All of your program's registers and storage areaS remain exactly as they 
were when program interruption occurred. The PSW that was in effect 
when your program was interrupted is in the program old PSW, at location 
X'28'. Use the DISPLAY command to examine its contents: 


cp display 28.8 


The program new PSW, or the PSW you see if you enter the command DISPLAY 
PSW, contains the address of the DEBUG routine. 


If, after using CP to examine your registers and storage areas, you 
can recover from the problem, you must use the STORE command to restore 
the PSW, specifying the address of the instruction just before the one 
indicated at location X'28'. For example, if the instruction address in 
your program is X'566' enter: 


cp store psw 0 20566 
cp begin 
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In this example, setting the first word of the PSW to 0O turns the wait 
bit off, so that execution can resume. 


Program Dumps 


When a program you execute under CMS abnormally terminates, you do not 
automatically receive a program dump. If, after attempting to use CMS 
and CP to debug interactively, you still have not discovered _ the 
problem, you may want to obtain a dump. You might also want to obtain a 
dump if you find that you are displaying large amounts of information, 
which is not practical on a terminal. 


Depending on whether you are using CMS DEBUG or CP to do your 
debugging, you can use the DUMP command to specify storage locations you 
want printed. The formats of the DUMP command (CP) and the DUMP 
subcommand (DEBUG) are a little different. See VM/SP CMS Command and 
Macro Reference for a discussion of the DEBUG subcommand, DUMP; see 
VM/SP CP Command Reference for General Users for a discussion of the CP 
DUMP command. 


In either event, you can selectively dump portions of your virtual 
storage, your entire virtual storage area, or portions of real storage. 
For example, in the debug environment, to dump the virtual storage space 
that contains your program, you would enter: 


dump 20000 20810 
The second value depends upon the size of your progran. 
From the CP environment, enter: 
cp dump t20000-20810 
The CP DUMP command allows you to request EBCDIC translation with the 


hexadecimal dump. The dump produced by the DEBUG subcommand does not 
provide EBCDIC translation. 


Debugging Modules 


You can debug nonrelocatable MODULE files (created with the GENMOD 
command) in the same way you can debug object modules (TEXT files). 


To load the MODULE into storage, use the LOADMOD command: 


loadmod mymod 
cp adstop 201C0 
start 


If you make any changes to a module while it is in your virtual 
storage area, you can generate a new module containing your changes 
provided your module file includes a load map (created with the MAP 
option in effect.) When you issue the GENMOD command, the changes 
become a permanent part of the executable module: 


loadmod nymod 
cp store 201C0 0002 
gennod mymod 


To debug MODULE files in this manner, you must have a listing of the 
program as it existed when the module was created. 
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Comparison Of CP And CMS Facilities For Debugging 


If you are debugging problems while running CMS, 


or CMS debugging tools. Refer to Figure 21 for a 


and CHS debugging tools. 
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Setting ad- | 
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Dumping l 
contents | 
of storage | 
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I 
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Displaying | 
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storage and | 
control | 
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at the | 
terminal. | 


Storing 
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Tracing 
information. 


ee ee rl 


CP 


Can set only one address 
storage at a time. 


The dump is printed in hexa- 
decimal format with EBCDIC 
translation. The storage 
address of the first byte of 
each line is at the left. 


The display is typed in hex- 
adecimal format with EBCDIC 
translation. The CP command 
displays storage keys, 
floating-point registers, 
and control registers. 


The amount of information 
stored by the CP command is 
limited only by the length of 
the input line. The informa- 
tion can be fullword aligned 
when stored. CP stores data 
in the floating-point and 
control registers, as well as 
in general registers. CP 
stores data in the PSW, but 
not in the CAW or CSW. 
However, data can be stored 
in the CAW or CSW by specify- 
ing the hardware address in 
the STORE command. 


CP traces: 

e All interruptions, in- 
structions and branches. 
SVC interruptions 

I/O interruptions 
Program Interruptions 
External interruptions 
Privileged instructions 
All user I/O operations 
Virtual and real CCW's 
All instructions 


The CP trace is interactive. 
You can stop it and display 
other fields. 
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Figure 21. 
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Comparison of CP and CMS Facilities for Debugging 


What Your Virtual Machine Storage Looks Like 


Figure 22 illustrates a simplified CMS storage map. The 
portion of storage that is of most concern to you is the 
user program area, Since that is where your programs are 
loaded and executed. The user program area and some of 

the other areas of storage shown in the figure are discussed 
below in general terms. 


X‘200000’ 


SSTAT 
YSTAT (SHARED) 
CMS NUCLEUS 


CMSSEG — OS Simulation 
EXEC 
EXEC2 
CMS Editor 
System Product Editor 


X‘1D0000’ 


X‘1A0000' 


X'n' 
Loader Tables (where n= your 
virtual machine 
storage size) 


User Program Area 
X'20000' 


Nucleus Free Storage 

X‘10000' 
Transient Program Area 

X‘E000' 


User Free Storage 


X'4710' 


System Control! Blocks, Pointers, Flags 


Figure 22. Simplified CMS Storage Map 
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When you issue a LOAD command (for OS or CMS programs) or a FETCH 
command (for DOS programs), and you do not specify the ORIGIN option, 
the first, or only, program you load is loaded at location X'20000', the 
beginning of the user program area. 


The upper limit, or taximurm size, of the user program area is 
determined by the storage size of your virtual machine. You can find 
out how large your virtual machine is by using the CP QUERY command: 


cp query virtual storage 


If you need to increase the size of your virtual machine, then you 
must use the CP command DEFINE. For example: 


cp define storage 1024k 


increases the size of your virtual machine to 1024K bytes. If you are 
in the CMS environment when you enter this command, you receive a 
message like: 


STORAGE = 01024K 
DMKDSP450W CP ENTERED; DISABLED WAIT PSW '00020000 00000000' 


and you must reload CMS with the IPL command before you can continue. 


You might need to redefine your virtual machine to a larger size if 
you execute a program that issues many requests for free storage, with 
the OS GETMAIN or VSE GETVIS macros. CMS allocates this storage fron 
the user program area. 


The loader tables, usually located at the top of the user's virtual 
storage, are used by the CMS loader to point to programs that have been 
loaded. You can change the size of the CMS loader tables the CMS SET 
LDRTBLS command. If you use the SET LDRTBLS command, you should issue 
it immediately after you IPL CMS. 


The transient program area is used for loading and executing 
disk-resident CMS MODULE files that have been created using the ORIGIN 
TRANS option of the LOAD command, followed by the GENMOD command. For 
more information on CMS MODULE files and the transient area, see 
"Executing Program Modules" in “Section 13. Programming for the CMS 
Environment." 


SHARED AND NONSHARED SYSTEMS 


The areas in storage labeled in Figure 22 as the CMS nucleus and the 
DCSS are system programs that are loaded by various types of requests. 
When you enter the command: 


cp ipl cms the area shown as the CMS nucleus is loaded with the CMS 
system, which is known to CP by its saved name, CMS. This saved system 
is a copy of the CMS system that is available for many users to share. 
When you are using CMS, you share it with other users who have also 
issued the IPL command to load the saved CMS system. By having many 
users Share the same system, CP can manage system resources’ nore 
efficiently. 


Under some circumstances, you may need to load the CMS system into 
your virtual machine by entering the IPL command as follows: 


cp ipl 190 
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This IPL command loads the CMS system by referring to its virtual 
address, which in most installations is 190. The copy of CMS you load 
this way is nonshared; it is your own copy, but it is the same systen, 
functionally, as the saved system CMS. 


Prior to issuing the command ‘ipl 190", you must define the size of 
your virtual machine so that it exceeds the end of the CMS nucleus. 
This is so that the nucleus can be loaded into your virtual machine. 


Some of the CP and CMS debugging commands do not allow you to trace 
or store information that is contained in shared areas of your virtual 
machine. For example, if you have entered the command: 


cp trace inst 


to trace instructions in your virtual machine, some of the instructions 
may be located in the CMS nucleus. If you have a shared copy of CMS, you 
receive a message like: 


DMKATS181E SHARED SYSTEM CMS REPLACED WITH NONSHARED COPY 


and CP loads a copy of CMS for you that you do not share with other 
users. 


Discontiquous Saved Seqments (DCSS) 


Some CMS routines and programs are stored on disks and loaded into 
storage as needed. These segments include the CMS editor, EXEC 
processor, and OS simulation routines; CMS/DOS; VSAM; and access method 
services. Beyond the end of your virtual machine address space is an 
area of storage into which these segments are loaded when you need then. 
Since this area is not contiguous with your virtual storage, the 
segments that are loaded in this area are called discontiguous saved 
segnents. 


These segments are loaded only when you need them, and are released 
from the end of your virtual machine when you are through using then. 
Like the CMS system, they are saved systems and can be’ shared by many 
users. For example, whenever you issue the EDIT command the segment 
named CMSSEG is loaded; when you enter the EDIT subcommands FILE or 
QUIT, the saved system CMSSEG is released. The other segments are named 
CMSDOS (for CMS/DOS), CMSBAM (for VSE/AF SAM interfaces), CMSVSAM (for 
VSAM interfaces), and CMSAMS (for access method services interfaces). 
These names are the defaults; they can be changed by the installation. 


You can specifically request a nonshared copy of a segment by loading 
the named system by volume rather than by name. If you do not do this 
before altering a shared segment (unless with the ADSTOP, TRACE, or 
STORE CP commands), CP issues the message DMKVMA456W and places you in 
console function mode. 


In addition, for the CMSSEG segment only, you can indicate an 


alternate segment to be loaded on the IPL command. The format of the 
IPL command to support this is: 


IPL jcuu PARM SEG=segmnentnane 
systemnane 


where; 


SEG=segmentnanme 
indicates the name of the saved segment to be loaded whenever the 
CMS editor, EXEC processor, or OS simulation routines are needed. 
Eight characters must be entered for segmentname; either assign an 
eight-character segment hame when you code the NAMESYS macro for 
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your installation, or be sure that the operator enters trailing 
blanks if segmentname is less than eight characters long. 


The CMS batch facility loads whatever segment is specified on the 
first IPL command issued for the batch virtual machine. Thus, if the 
first IPL command for a CMS batch facility machine is: 

IPL CMS PARM SEG=CMSSEG02 


all subsequent IPL commands issued by the CMS batch facility will 
specify the same segment name (CMSSEGQ2). 


For additional information on saved systems, discontiguous' saved 


segments, and CMS virtual storage, see the VM/SP System Programmer's 
Guide. nae 
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Section 12. Using the CMS Batch Facility 


The CMS batch facility provides away of submitting jobs for batch 
processing in CMS. You can use the CMS batch facility when: 


e You have a job (like an assembly or execution) that takes a lot of 
time, and you want to be able to use your terminal for other work 
while the time-consuming job is being run. 


e You do not have access to a terminal. 


The CMS batch facility is really a virtual machine, generated and 
controlled by the system operator, who logs on VM/SP using the batch 
userid and invoking the CMSBATCH command. All jobs submitted for batch 
processing are spooled to the userid of this virtual machine, which 
executes the jobs sequentially. To use the CMS batch facility at your 
location, you must ask the system operator what the userid of the batch 
virtual machine is. 


Submitting Jobs to the CMS Batch Facility 


Under areal OS or DOS system, jobs submitted in batch sode are 
controlled by JCL specifications. Batch jobs submitted to the CMS batch 
facility are controlled by the control cards /JOB, /SET, and /*, and by 
CMS commands. 


Any application or development program written in a language 
supported by VM/SP may be executed on the batch facility virtual 
Machine. However, there are restrictions on programs using certain CP 
and CMS commands, as described later in this section. 


INPUT TO THE BATCH MACHINE 


Input records must be in card-image format, and may be punched on real 
cards, placed ina CMS file with fixed-length, 80-character records, or 
punched to your virtual card punch. These jobs are sent to. the batch 
virtual machine in one of two ways: 


e By reading the real punched card input into the system card reader 


e By spooling your virtual card punch to the virtual reader of the 
batch virtual machine 


When you submit a real card deck to the batch machine, the first card 
in the deck must be a CP ID card. The ID card takes the form: 


re ee TS ee ee Ee ee eT ey 
[ID userid j 
SS a ee a a ee | 


where ID must begin in card column one and be separated from userid (the 
batch facility virtual machine userid) by one or more blanks. 


Section 12. Using the CMS Batch Facility 253 


For example, if your installation's batch virtual machine has a 
userid of BATCH1, you punch the card: 


ID BATCH! 
and place it in front of your deck. 


When you are going to submit a job using your virtual card punch, you 
must first be sure that your punch is spooled to the virtual reader of 
the batch virtual machine: 


cp spool punch to batch! 


Submitting Virtual Card Input t 


the CMS Batch Facility 


Virtual card input can be spooled to the batch machine in several ways. 
You may create a CMS file that contains the input control cards and use 
the CMS PUNCH command to punch the virtual cards: 


punch batch jcl (noheader 


When you punch a file this way, you must use the NOHEADER option of the 
PUNCH command, since the CMS batch facility cannot interpret the header 
card that is usually produced by the PUNCH command. AS it does with 
cards in an invalid format, the batch virtual machine would flush the 
header card. 


You can use an EXEC procedure to submit input to the batch machine. 
From an EXEC, you can punch one line at a time into your virtual punch, 
using the &PUNCH and §&BEGPUNCH EXEC control statements. When you do 
this, you must remember to use the CP CLOSE command to release the spool 
punch file when you are finished: 


CP CLOSE PUNCH 


If you are using the EXEC to punch individual lines and entire CMS files 
to be read by the batch virtual machine as one continuous job strean, 
you must remember to spool your punch accordingly: 


CP SPOOL PUNCH CONT 

S&PUNCH /JOB BOSWELL 999888 
PUNCH BATCH JCL * (NOHEADER 
CP SPOOL PUNCH NOCONT 

CP CLOSE PUNCH 


The /JOB and /* Cards 


A /JOB card must precede each job to be executed under the batch 
facility. It identifies your userid to the batch virtual machine and 
provides accounting information for the system. It takes the form: 


"A me SE ak cP SE IRSA SA NG Sa a aa a 
| /JOB userid accntnun [ jokname] [comments ] | 
Mn hh the heen dcerememesnveal 
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where: 


userid is your user identification, or the userid under which you 
want the job submitted. This parameter controls: (1) The 
userid charged by the CP accounting routines for the systen 
resources used during a job. (2) The name and distribution 
code that appear on any spooled printer or punch output. (3) 
The userid to whom status messages are sent while the batch 
machine is executing the job. 


Note: Items 1 and 2 are correct only if the directory for the 
userid involved contains the accounting option. 


accnotnum is your account number. This account number appears in the 
accounting data generated at the end of your job. It 
overrides the account number in the CP directory entry for the 
userid specified for this job. 


jobnane is an optional parameter that specifies the name of the job 
being run. If you specify a jobname, it appears as' the CP 
spool file identification in the filetype field. The filename 
field always contains CMSBATCH. See "Batch Facility Output" 
below. 


comments may be any additional information you want to provide. 


The /* card indicates the end of a job to the batch facility. It 
takes the forn: 


| /* l 


| ee ee ee er a re ee ET 


The batch facility treats all /* cards after the first as null cards. 
Therefore, if you want to ensure against the previous job not having a 
/7* end—of-—job indicator, you should precede your /JOB card with a /* 
card. 


The /* card is also treated as an end—of—file indicator when a file 
is being read from the input stream. This is a special technigue used in 
submitting source or data files through the card reader and is discussed 
under "A Batch EXEC for Non—CMS Users." 


The /SET Card 


The /SET card sets limits ona system's time, printing, and punching 
resources during the execution of a job. It takes the form: 


ee Piety ee ee a ag eee Pe ee pe Pe Ra ee ep ee eg ey ee ee ee 
| /SET [TIME seconds] [PRINT lines] [PUNCH cards] | 
a ae ee a a Se ee ee ne ee 


seconds is a decimal value that specifies the maximum number of 
seconds of virtual CPU time a job can use. 


lines is a decimal value that specifies the maximum number of lines 
a J9b can print. 
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cards is a decimal number that specifies the maximum number of cards 
a job can punch. 


The default values for the batch facility are set at 32,767 seconds, 
printed lines, and punched cards per job. Any new limits defined using 
the /SET card must be less than these maximum settings. The systen 
resources can be set at lesser values than the default values by an 
installation's system programmer; be sure you know the maxinun 
installation values for batch resource limits before you use the /SET 
card. 


A /SET card can appear anywhere in the job following the /JOB card. 
The new limits defined by the /SET card apply only to the part of the 
job that follows the /SET card. 


A job can contain up to three /SET cards (one for each operand); a 
/SET card cannot be entered more than once for the same operand. 


Only use /SET cards for the operands whose values you want to change 
from the default; the default values are reset between jobs. A /SET 
card for an operand overrides its default but does not reset the other 
operands. 


HOW THE BATCH FACILITY WORKS 


The CMS batch facility, once initialized, runs continuously. When it 
begins executing a job, it sends a message to the userid of the user 
submitting the job. If you are logged on when the batch machine begins 
executing a job that you sent it, you receive the message: 


MSG FROM BATCHID: JOB "yourjob' STARTED 
When the batch machine finishes processing a job, it sends the message: 
MSG FROM BATCHID: JOB ‘yourjob* ENDED 


where yourjob is the jobname you specified on the /JOB card. Before it 
reads the next job from its card reader, the batch virtual machine; 


Closes all spooling devices and releases spool files 

Resets any spooling devices identified by the CP TAG command 
Detaches any disk devices that were accessed 

Punches accounting informaticn to the system 

Reloads CMS 


All of this "housekeeping" is done by the CMS batch facility so that 
each job that is executed is unaffected by any previous jobs. 


If ayjob that you sent to the batch virtual machine terminates 
abnormally (abends), the batch machine sends you a message: 


MSG FROM BATCHID: JOB ‘yourjok® ABEND 


and spools a CP storage dump of your virtual machine to the printer. 
The remainder of your job is flushed. 


Whenever the batch virtual machine has read and executed all of the 
jobs in its card reader, it waits for more input. 
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Preparing Jobs for Batch Execution 


When you want to submit a job to the CMS batch facility for execution, 
you should provide the same CMS and CP commands you would use to prepare 
to execute the same job in your own virtual machine. 


You must provide the batch virtual machine with read access to any 
disk input files that are required for the job. You do this by supplying 
the LINK and ACCESS command lines necessary. The batch virtual machine 
has an A-disk (195), so you can enter commands to access your disks as 
read-only extensions. For example, if you wanted the batch machine to 
execute a program module named LONDON on your 291 disk, your input file 
might contain the following: 


/JOB FISH 012345 

CP LINK BOSWELL 291 291 RR SECRET 
ACCESS 291 B/A 

LONDON 


Similarly, if you are using the batch virtual machine to execute a 
program using input and output files, you must supply the file 
definitions: 


CP LINK ARDEN 391 391 RR FOREST 
ACCESS 391 B/A 

FILEDEF INFILE DISK VITAL STAT B 
FILEDEF OUTFILE PUNCH 

CP SPOOL PUNCH TO BOSWELL 

LONDON 


If you expect printed or punched output from your job, you may need 
to include the spooling commands necessary to control the output. In 
the above example, the batch machine's punch is_ spooled to userid 
BOSWELL's virtual reader. 


Any output printer files produced by your job are spooled by the 
batch virtual machine to the printer. These files are spooled under your 
userid and with the distribution code associated with your userid, 
provided the userid's directory has the accounting option set. You can 
change the characteristics of these output files with the CP SPOOL 
command: 


CP SPOOL E CLASS T 


If you want output to appear under a name other than your userid, use 
the FOR operand of the SPOOL command: 


CP SPOOL E FOR JONSON 


Output punch files are spooled, by default, to the real system card 
punch (under your userid), unless you issue a SPOOL command in the batch 
job to control the virtual card punch of the batch virtual machine. 
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RESTRICTIONS ON CP AND CMS COMMANDS IN BATCH JOBS 


The batch facility permits the use of many CP and most CMS commands. 
The following CP commands can be used to control the batch virtual 
machine: 


CHANGE! MSG 
CLOSE! QUERY 
DETACH2 REWIND 
DUMP SMSG 
DISPLAY SPOOL? 
LINK$ STORE 
TAG 
Notes: 


1. These commands may not be used to affect the virtual card reader. 


2. You can not use this command to detach any spooling devices or the 
system or IPL disks. 


3. The LINK command must be entered on one line in the format: 
CP LINK userid vaddr vaddr mode password 


None of the LINK command keywords (AS, PASS, TO) are accepted. If 
the disk has no password associated with it, you must enter the 
password as ALL. A maxmum of 26 links’ may be in effect at any one 
time. 


All CP commands in a batch job must be prefaced with the "cp" 
command. 


Since the batch virtual machine reads input from its card reader, you 
cannot use the following commands or operands that affect the card 
reader: 


ASSGN SYSxxx READER (CMS/DOS only) 
DISK LOAD 

FILEDEF READER 

READCARD 


The RDCARD macro cannot be used by jobs that run under the CMS batch 
machine. 


Invalid SET command operands are: 


BLIP PROTECT 
IMPCP REDTYPE 
INPUT RELPAGE 
OUTPUT 


All of the other CMS SET command operands can be used in a job executing 
in the batch virtual machine. All forms of the CP SET command are 
invalid. 


Note: If the SET TIMER REAL command is used for the batch machine, the 


timer expires every two seconds (including while batch is waiting for 
the reader). To avoid this problem, use the command SET TIMER ON. 


258 IBM VM/SP CMS User's Guide 


BATCH FACILITY OUTPUT 


Any files that you request to have printed during your job's execution 
are spooled to the real system printer under your userid, unless you 
have spooled it otherwise. Once released for processing, these output 
files are under the control of the CP spooling facilities; if you are 
logged on, you can control the disposition of these files before they 
are printed with the CLOSE, PURGE, ORDER, and CHANGE commands. See the 
following section “Purging, Reordering, and Restarting Batch Jobs." 


Output files produced by the batch virtual machine are identifiable 
by the filename CMSBATCH in the CP spool file name field. The spool file 
type field contains the filetype JOB, unless you specified a jobname on 
the /JOB card. This applies to both printer and punch output files. 


In addition to your regular printed output, the CMS batch facility 
spools a console sheet that contains a record of all the lines read in, 
and the responses, error messages, and return codes that resulted fron 
command or program execution. This file is identified by a spool file 
hame of BATCH and a spool file type of CONSOLE. 


Purging, Reordering, and Restarting Batch Jobs 


When required, you can control the execution of batch virtual machine 
jobs by purging, reordering, and restarting them; by the same token, 
because all the closed printer files are queued for system output under 
the submitting userid, you can change, purge, or reorder these files 
prior to processing on the system printer. 


To purge a job executing under the batch monitor, follow the 
procedure below: 


1. Signal attention and enter the virtual machine environment. 
2. Enter the HX (halt execution) Immediate command. 
3. Disconnect the virtual machine using the CP DISCONN command. 

The HX command causes the batch facility to abnormally terminate. 
This provides the user with an error message and a CP dump of the batch 
facility virtual machine. The batch monitor then loads itself again and 
starts the next job (if any). 


To purge an individual input spool file that is not yet executing, 
issue the CP PURGE command: 


PURGE READER spoolid 
In the format above, spoolid is the spool file number of the job to 
be purged from the batch virtual machine's job queue. For example, the 
statenent: 
PURGE READER 123 


would purge 123 from the batch virtual machine's job queue. 


To reorder individual spool files in the batch facility's job queue, 
use the CP ORDER command: 


ORDER READER spoolid1 spoolid2... 


In this format, spoolid1 and spoolid2 are the assigned spool file 
identifications of the jobs to be reordered. 
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You can determine which jobs are in the queue by using the CP QUERY 
command: 


QUERY READER ALL 


This QUERY command lists the filenames and filetypes of all the jobs 
in the batch virtual machine's job queue. You can then reorder then, 
using the ORDER command. 


Using CMS EXEC Files for Input to the Batch Facility 


There are a variety of ways that CMS EXEC procedures can help facilitate 
the submission of jobs to the CMS batch facility. You can prepare an 
EXEC file that contains all of the CMS commands you want to execute, and 
then pass the name of the EXEC to the batch virtual machine. For 
example, consider the files COPY JCL and COPYF EXEC: 


COPY JCL: /JOB CARBON 999999 
EXEC COPYF 


/* 


COPYF EXEC: COPYFILE FIRST FILE A SECOND 
COPYFILE THIRD FILE A FOURTH 


Then, if you enter the commands: 


Cp spool punch to cmsbatch 
punch copy jcl * (noheader 


the commands in the EXEC file are executed by the batch virtual machine. 


You could also use a CMS EXEC to punch input to the batch virtual 
machine. Using the same commands as in the example above, you might 
have a CMS EXEC named BATCOPY: 


CP SPOOL PUNCH TO BATCH3 

&PUNCH /JOB CARBON 999999 

&PUNCH COPYFILE FIRST FILE A SECOND 
&PUNCH COPYFILE THIRD FILE A FOURTH 
&PUNCH /* 

CP CLOSE PUNCH 


Then, when you enter the EXEC name: 
batcopy 
the input lines are punched to the batch virtual machine. 

The examples above are very simple; you probably would not go to the 
trouble of sending such a job to the batch virtual machine for 
processing. The examples do, however, illustrate the two basic ways 
that you can use CMS EXEC procedures with the batch facility: 


1. Invoking a CMS EXEC procedure from a batch virtual machine 


2. Using a CMS EXEC procedure to create a job stream for the batch 
Virtual machine 


In either case, the EXECS that you use may be very simple or very 
complicated. In the first instance, an EXEC might contain many steps, 
with control statements to conditionally control execution, error 
routines, and so on. 
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In the second instance, you might have an EXEC that is versatile so 
that it can be invoked with different arguments so as to satisfy more 
than one situation. For example, if you want to create a_ simple CMS 
EXEC to send jobs to the batch virtual machine to be assembled, it might 
contain: 


CP SPOOL PUNCH TO BATCH3 CONT 

&PUNCH /JOB ARIEL 888888 

&PUNCH CP LINK ARIEL 191 391 RR LINKPASS 
&PUNCH ACCESS 391 B/A 

&PUNCH ASSEMBLE &1 (PRINT 

&PUNCH CP SPOOL PUNCH TO ARIEL 

SPUNCH PUNCH 6&1 TEXT A (NOHEADER 

&PUNCH /* 

CP SPOOL PUNCH NOCONT CLOSE 


If this file were named BATCHASM EXEC, then whenever you wanted the CMS 
batch facility to assemble a source file for you, you would enter: 


batchasnm filename 


and the batch virtual machine would assemble the source file, print the 
listing, and send you a copy of the resulting TEXT file. 


SAMPLE SYSTEM PROCEDURES FOR BATCH EXECUTION 


To extend the above example a_ little further, Suppose you wanted to 
process source files in languages other than the assembler language. You 
want, also, for any user to be able to use this CMS EXEC. You might 
have a separate EXEC file for each language, and an EXEC to control the 
submission of the job. This example shows the controlling EXEC file 
BATCH and the ASSEMBLE EXEC. 


BATCH EXEC: 


THIS CMS EXEC SUBMITS ASSEMBLIES/COMPILATIONS TO CMS BATCH 


- PUNCH BATCH JOB CARD; 
- CALL APPROPRIATE LANGUAGE EXEC (&3) TO PUNCH EXECUTABLE COMMANDS 


* tee te 


&CONTROL ERROR 

SIF GINDEX GT 2 &SKIP 2 

STYPE CORRECT FORM IS: BATCH USERID FNAME FTYPE (LANGUAGE) 
SEXIT 100 

SERROR &GOTO -ERR1 

CP SPOOL D CONT TO BATCHCMS 

GPUNCH /JOB &1 1111 52 

&PUNCH CP LINK &1 191 291 RR SECRET 
SPUNCH ACCESS 291 B/A 

EXEC 63 6&2 6&1 

&PUNCH /* 

CP SPOOL D NOCONT 

CP CLOSE D 

CP SPOOL D OFF 

SEXIT 

-ERR1 SEXIT 100 


Section 12. Using the CMS Batch Facility 26 1 


ASSEMBLE EXEC: 
CORRECT FORM IS: ASSEMBLE FNAME USERID 
PUNCH COMMANDS TO: 


- INVOKE CMS ASSEMBLER 
- RETURN TEXT DECK TO CALLER 


i 


&CONTROL ERROR 
SERROR &GOTO -ERR2 

&PUNCH GLOBAL MACLIB UPLIB CMNSLIB OSMACRO 
EPUNCH CP MSG &2 ASMBLING ' &1 ° 
&PUNCH ASSEMBLE 6&1 (PRINT NOTERM) 
EPUNCH CP MSG &2 ASSEMBLY DONE 
&PUNCH CP SPOOL D TO &2 NOCONT 
&PUNCH PUNCH &1 TEXT A1 (NOHEADER) 
& BEGPUNCH 

CP CLOSE D 

CP SPOOL D OFF 

RELEASE 291 

CP DETACH 291 

& END 

&EXIT 

-ERR2 SEXIT 102 


Executing the Sample CMS EXEC Procedure 


If the above CMS EXEC procedure is invoked with the line: 
batch fay payroll assemble 


the BATCHCMS virtual machine's card reader should contain the following 
statements (in the same general form as a FIFO console stack): 


/JOB FAY 1111 PAYROLL 

CP LINK FAY 191 291 RR SECRET 
ACCESS 291 B/B 

GLOBAL MACLIB UPLIB CMSLIB OSMACRO 
CP MSG FAY ASMBLING " PAYROLL * 
ASSEMBLE PAYROLL (PRINT NOTERM) 
CP MSG FAY ASSEMBLY DONE 

CP SPOOL D TO FAY NOCONT 

PUNCH PAYROLL TEXT A1 (NOHEADER) 
CP CLOSE D 

CP SPOOL D OFF 

RELEASE 291 

CP DETACH 291 

/* 


When the batch facility executes this job, the commands are executed as 
you see them: if you are logged on, you receive, in addition to the 
normal messages that the batch facility issues, those messages that are 
included in the EXEC. 


A BATCH EXEC FOR A NON-CMS USER 


Many installations run the CMS batch facility for non-CMS users to 
submit particular types of jobs. Usually, a series of CMS EXEC files 
are stored on the system disk so that each user only needs include a 
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card to invoke the EXEC, which executes the correct CMS commands to 
process data included with the job strean. 


For example, if a non-CMS user wanted to compile FORTRAN source 
files, the following BATFORT EXEC file could be stored on the system 
disk: 


&CONTROL OFF 

FILEDEF INMOVE TERM (RECFM F BLOCK 80 LRECL 80 

FILEDEF OUTMOVE DISK &1 FORTRAN Al (RECFM F LRECL 80 BLOCK 80 
MOVEFILE 

GLOBAL TXTLIB FORTRAN 

FORTGI &1 (PRINT) 

&PORTRET = SRETCODE 

SIF GRETCODE NE 0 &GOTO -EXIT 

PUNCH &1 TEXT A1 (NOHEADER) 

-EXIT SEXIT &FORTRET 


To use this EXEC, a non-CMS user might place the following real card 
deck in the system card reader: 


ID CMSBATCH 
7/JOB JOEUSER 1234 JOB10 
BATFORT JOEFORT 


source file 


7* (end-of-file indicator) 
/* (end-of-job indicator) 


When the batch virtual machine executes this job, it begins reading 
the EXEC procedure from disk, and executes one line at a time. When it 
encounters the MOVEFILE command, it begins reading the source file fron 
its card reader (the batch facility interprets a terminal read asa 
request to read from the card reader). It continues reading until it 
reaches the end-of-file indicator (the /* card), and then resumes 
processing the EXEC on the next line following the MOVEFILE command 
line. 


Additional functions may be added to this EXEC procedure, or others 
may be written and stored on the system disk to provide, for example, a 
compile, load, and execute facility. These EXEC procedures would allow 
an installation to accommodate the non-CMS users and maintain comgon 
user procedures. 
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Section 13. Programming for the CMS Environment 


This section contains information for assembler language programmers who 
May occasionally need to write programs to be used in the CMS 
environment. The conventions described here apply only to CMS virtual 
machines; you can not execute these programs under any other operating 
systems. 


Program Linkage 


Program linkages, in CMS, are generally made by means of a supervisor 
call instruction, SVC 202. The SVC handling routine takes care of 
program linkage for you. The registers used and their contents are 
discussed in the following paragraphs. 


Register 0: If the command is called from the terminal or from an EXEC 2 
exec, register 0 points to an ‘textended' plist, which contains addresses 
referring to the extended command as it was initially entered by the 
user. 


Register 1: Points to a parameter list of Successive doublewords. The 
first entry in the list is the name of the called routine or prograa, 
and any successive doublewords may contain arguments passed to the 
program. Parameter lists are discussed under “Parameter Lists." 


Register 13: Contains the address of a 24-fullword save area, which you 
can use to save your caller's registers. This save area is provided to 
satisfy standard OS and DOS linkage conventions; you do not need to use 
it in CMS, since the SVC routines save the registers. 


Register 14: Contains the return address of the SVC handling routines. 
You must return control to this address when you exit from your progran. 


The CMS routines that get control by way of register 14 close files, 
update your disk file directory, and calculate and type the time used in 
program execution. These values appear in the CMS ready message, which 
is displayed at your terminal when your program finishes execution; 


R;T=n.-nn/x. xx hh:mm:ss 


where n.nn is the CMS CPU time (in seconds) and x.xx is the combined CP 
and CMS CPU time. hh:mm:ss is the time of day in hours, minutes, and 
seconds. 


Note: If CMS cannot calculate a valid time, it will display *.** in 
place of n.nn/x.xx. If the CMS CPU time or the combined CP and CMS CPU 
time exceeds 35 minutes, the printed time may be incorrect. 


Registers 12 and 15: Contain your program's entry point address. You can 
use this address to establish immediate addressability in your progran. 
You should not use Register 15 as a base address, however, since all CMS 
SvVCs use it for communication with your programs. 


Figure 23 shows a sample CMS assembler language program entry and exit. 
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NS a ee ee ge a Me ee ee Tg ge ee ae EU Se ee ee eee ee ee 
PROGRAM CSECT 


| | 
| USING PROGRAM, 12 ESTABLISH ADDRESSABILITY { 
| sT 14,SAVRET SAVE RETURN ADDRESS IN R14 | 
| - | 
| : [ 
| : | 
| L 14,SAVRET LOAD RETURN ADDRESS | 
| LA 15,0 SET RETURN CODE IN R15 | 
| BR 14 GO { 
| SAVRET DS F SAVE AREA | 


Figure 23. Sample CMS Assembler Program Entry and Exit Linkage 


RETURN CODE HANDLING 


Register 15, in addition to its role in entry linkage, is also used in 
CMS as a return code register. All of the CMS internal routines pass a 
completion code by way of register 15, and the SVC routines that receive 
control when any program completes execution examine register 15. 


If register 15 contains a nonzero value, this value is placed in the 
CMS ready message, following the "R": 


R (nnnnn) ;T=n.-nn/x.xx hh:mm:ss 


When you are executing programs in CMS, it is good practice, if your 
programs do not use register 15 as a return code register, to place a 
zero in it before transferring control back to CMS. Otherwise, the ready 
message may display meaningless data. 


PARAMETER LISTS 


When you execute a program from your terminal, a CMS scan routine sets 
up a parameter list based on your command input line. The parameter list 
is doubleword aligned, with parameters occupying successive doublewords. 
The scan routine recognizes blanks and parentheses as argument 
delimiters; parentheses are placed, in the parameter list, in separate 
doublewords. 


The RO parameter list contains three addresses that indicate the 
extended form of the command as it was entered from the terminal. 


For example, if you have a CMS MODULE file named TESTPROG, and you 
call it with the command line: 


testprog (file2) 


The scan routine sets up the parameter list: 


CMNDLIST DS OD 
DC CL8'TESTPROG! 
DC CL8t(! 
DC CL8'FILE2* 
DC CL8")* 
DC 8X'FF! 


The last doubleword is made up of all X'F's. This acts as delimeter to 
indicate the end of the parameter list. 


If you enter any argument longer than eight characters, the argument 
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{| is truncated and only the first eight characters appear inthe R1 
| parameter list. However, no error condition results. 


| The RO extended parameter list is set up as follows: 


| EPLIST DC A (CMDSTART) 
| DC A (ARGSTART) 
DC A (ARGEND) 


| Where the RO extended parameter list would refer to the same command 
| in the following manner: 


| CMDSTART DC C*'testprog § 
| ARGSTART DC C*(file2)!' 
| ARGEND EQU * 


Using Parameter Lists 


The scan routine that sets up this parameter list places the address of 
the list in register 1 and then calls the SVC handling routine. The SVC 
routine gives control to the program named in the first doubleword of 
the parameter list. 


When your program receives control, it can examine the parameter list 
| passed to it by way of register 1 and register 0. 


You can use this technigue, also, to call CMS commands from your 
programs. 


When you use the LOAD and RUN commands to execute a program in CMS, 
you can pass an argument list to the program on the command line. For 
example, if you enter: 


load myprog 
start * runl proga 


the * indicates that the entry foint is to be defaulted. The arguments 
RUN1 and PROGA are placed ina parameter list of doublewords and 
register 1 contains the address of this list when your program receives 
control. If you want to use the RUN command to perform the’ load and 
start functions, you could enter: 


run myprog (runtl proga 
The parenthesis indicates the beginning of the argument list. 


To detect the absence of a parameter list that occurs when the LOAD 
command START option is used, your program may test the doubleword 
pointed to by register 1 for a delimiter made up of 1's in all of the 
bit positions. 


Calling a CMS Command from a Program 


| You can call a CMS command from a program by setting up a_ Register 1 
parameter list, like that shown above, and then issuing an SVC 202. The 
parameter list you set up must have doublewords that contain the 
parameters or arguments you would enter if you were entering the command 
from the terminal. For example: 
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PUNCHER DS OD 
DC CL8"PUNCH' 


DC CL8'NAME? 
DC CL8'TYPE! 
DC CL8*#! 
DC CL8'(! 
DC CL8*NOH* 
DC 8X" FF! 


Note: If you are using EXEC 2, refer to VM/SP EXEC 2 REFERENCE, and 
VM/SP System Programmer's Guide for information on parameter lists 
without tokens. 


In your program, when you want to execute this command, you should load 
the address of the list into register 1, and issue the supervisor call 
instruction (SVC) as follows: 


LA 1, PUNCHER 
SVC 202 
DC AL4 (ERROR) 


When you issue an SVC 202, you must supply an error return address in 
the four bytes immediately after the SVC instruction. If the return code 
(register 15) contains a nonzero value after returning from the SVC 
call, control passes to the address specified unless the address is 
equal to 1. If the address is 1, return is made to the next instruction 
after the 'DC AL4(1)' instruction. In the above example, control would 
go to the instruction at the label ERROR. 


If you want to ignore errors, you can use the sequence; 


LA 1, PUNCHER 
SVC 202 
DC AL4 (1) 


If you do not specify an error address, control is returned to the next 
instruction after a normal return, but if there was an error executing 
the CMS command, your program terminates execution. 


If you want to execute a CP command or an EXEC procedure from a 
program, you must use the CP and EXEC commands; for example: 


SPOOL DS OD 
DC CL8'CP* 
DC CL8* SPOOL! 
DC CL8"PRINTER' 
DC CL8"*CLASS' 
DC CL8*S* 
DC SX'*FF! 

EXEC DC CL8" EXEC! 
DC CL8"*PFSET! 
DC SX*FF!® 


It is not possible to enter a parameter that is longer than eight 
characters this way. 


As an alternative, you can use the CMS LINEDIT macro to call a CP 
command from a program. Specify DISP=CPCOMM on the macro instruction; 
for example: 

LINEDIT TEXT="SPOOL E CLASS S*!,DISP=CPCOMM,DOT=NO 


On return from the execution of the LINEDIT macro instruction, register 
15 contains the return code from the CP command. 
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The LINEDIT macro is described in VM/SP CMS Command and Macro 
Reference. 


Another way to execute acCP command from a program is to. use the 
DIAGNOSE x'08* instruction. For additional information on this, see 


WM/SP System Programmer's Guide. 


Executing Program Modules 


MODULE files, in CMS, are nonrelocatable programs. Using the GENMOD 
command, you can create a module from any program that uses OS or CMS 
macros. When you create a module, it is generated at the virtual 
storage address at which it is loaded, for example: 


load myprog 
genmod testit 


The CMS disk file, TESTIT MODULE A, that is created as a result of this 
GENMOD command, always begins execution at location X'20000"', the 
beginning of the user program area. 


If you want to call your own program modules using SVC 202 
instructions, you must be careful not to execute a module that uses the 
same area of storage that your program occupies. If you want to call a 
module that executes at location X'20000', you can load the calling 
program at a higher location; for example: 


load myprog (origin 30000 


As long as the MODULE file called by MYPROG is no longer than X*10000' 
bytes, it will not overlay your progran. 


Many CMS disk-resident command modules also execute in the user 
program area. When using the GENMOD command with the STR option, the 
user area storage pointers are reset. This could cause errors upon 
return to the original progran. 


THE TRANSIENT PROGRAM AREA 


To avoid overlaying programs executing in the user program area, you can 
generate program modules to run in the CMS transient area, which isa 
two-page area of storage that is reserved for the execution of programs 
that are called for execution frequently. Many CMS commands run in this 
area, which is located at X'E000'. Programs that execute in this area 
run disabled. 


To generate a module to run in the transient area, use the ORIGIN 
TRANS option when you load the TEXT file into storage, then issue the 
GENMOD command: 


load myprog (origin trans 
genmod setup (str 


Note: If a program running in the user area calls a transient routine in 
which a module was generated using the GENMOD command with the STR 
option, the user area storage pointers will be reset. This reset 
condition could cause errors upon return to the original program (for 
example, when OS GETMAIN/FREEMAIN macros are issued in the user 
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progran). 


The two restrictions placed on command modules executing in the 
transient area are: 


1. They may have a maximum size of 98192 bytes, since that is the size 
of the transient area. This size includes any free storage acquired 
by GETMAIN macros. 


2. They must be serially reusable. When a program is called by an SVC 
202, if it has already been loaded into the transient area, it is 
not reloaded. 


The CMS commands that execute in the transient area are: ACCESS, 
ASSGN, COMPARE, DISK, DLBL, FILEDEF, GENDIRT, GLOBAL, LISTFILE, MODMAP, 
OPTION, PRINT, PUNCH, QUERY, READCARD, RELEASE, RENAME, SET, SVCTRACE, 
SYNONYM, TAPE, and TYPE. 


CMS Macro Instructions 


There are a number of assembler language macros distributed with the CMS 
system that you can use when you are writing programs to execute in the 
CMS environment. They are in the macro library CMSLIB MACLIB, which is 
normally located on the system disk. There are macros to manipulate CMS 
disk files, to handle terminal communications, to manipulate unit record 
and tape input/output, and to trap interruptions. These macros are 
discussed in general terms here; for complete format descriptions, see 


MACROS FOR DISK FILE MANIPULATION 


Disk files are described in CMS by means of a file system control block 
(FSCB). The CMS macro instructions that manipulate disk files use FSCBs 
to identify and describe the files. When you want to manipulate a CMS 
file, you can refer to the file either by its file identifier, 
specifying "filename filetype filemode' in quotation marks, or you can 
refer to the FSCB for the file, specifying FSCB=fscb, where fscb is the 
label on an FSCB macro. 


To establish an FSCB for a file, you can use the FSCB_ macro 
instruction specifying a file identifier; for example: 


INFILE FSCB ‘INPUT TEST Atl* 


You can also provide, on the FSCB macro instruction, descriptive 
information to be used by the input and output macros. If you do not 
code an FSCB macro instruction for a file, an FSCB is’ created inline 
(following the macro instruction) when you code an FSREAD, FSWRITE, or 
FSOPEN macro instruction. 


The format of an FSCB is listed in Figure 24, followed by a 
description of each of the fields. 
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| Label Description [ 
DS ee aa ee | 
| FSCBCOMM DC CL8* ¢ File system command | 
| FSCBFN DC cCL8* * Filename | 
| FSCBFT DC CLE" ¢ Filetype | 
| FSCBFM DC CL2* ¢ Fileszode | 
| FSCBITNO DC H'o? Relative record number (RECNOQ) | 
| FSCBBUFF DC A*Q'* Address of buffer (BUFFER) ; 
| FSCBSIZE DC F'o?t Number of bytes to read or write (BSIZE) [ 
{| FSCBFV DC CL2'*F* Record format - F or V7 (RECFM) { 
| FSCBFLG EQU  FSCBFY+1 Flag byte | 
| FSCBNOIT DC H't? Number of records to read or write (NOREC) | 
| FSCBNORD DC AL4 (0) Number of bytes actually read | 
| FSCBAITN DC AL4 (0) Extended FSCB relative record number | 
| FSCBANIT DC AL4 (1) Extended FSCB relative number of records | 
| FSCBWPTR DC AL4 (0) Extended FSCB relative write pointer | 
| FSCBRPTR DC AL4 (0) Extended FSCB relative read pointer { 
Lae ee oe — oo wn ow a a wn wr a a a wr a a a www a a wr wn a ww nn nw ee ee ener eee J 


Figure 24. FSCB Format 


The fields FSCBAITN, FSCBANIT, FSCBWPTR, and FSCBRPTR are only 
generated in the FSCB when the extended format FSCB is requested (FORM=E 
is coded on the FSCB macro instruction). In this case, the fields 
FSCBITNO and FSCBNOIT are reserved fields. Extended format FSCBs must 
be used’ to manipulate files larger than 65,533 items. The labels shown 
above are not generated by the FSCB macro; to reference fields within 
the FSCB by these labels, you must use the FSCBD macro instruction to 
generate a DSECT. 


FSCBCOMM: When the FSCBFN, FSCBFT, and FSCBFM fields are filled in, you 
can fill in the FSCBCOMM field with the name of a CMS command and use 
the FSCB as a parameter list for an SVC 202 instruction. (You must 
place a delimiter to mark the end of the command line.) 


FSCBFN, FSCBFT, FSCBFM: The filename, filetype and filemode fields 
identify the CMS file to be read or written. You can code the fileid on 
a macro line in the format 'filename filetype filemode' or you can use 
register notation. If you use register notation, the register that you 
specify must point to an 18-byte field in the format: 


FILEID DC CL8'filename't 
DC CL8' filetype? 
Dc CL2'fn' 


The fileid must be specified either in the FSCB for a file or on the 
FSREAD, FSWRITE, FSOPEN, or FSERASE macro instruction you use that 
references the file. 


FSCBITNO: For an FSCB without the FORM=E option, the record or iten 
number indicates the relative record number of the next record to be 
read or written; it can be changed with the RECNO option. The default 
value for this field is 0. When you are reading files, a 0 indicates 
that records are to be read sequentially, beginning with the first 
record in the file. When you are writing files, a0 indicates that 
records are to be written sequentially, beginning at the first record 
following the end of the file, if the file already exists, or with 
record 1, if it is a new file. 


For an FSCB generated with the FORM=E option, the FSCBAITN field 
contains the record or item number. The FSCBITNO field is reserved. 


Whenever you read discontiguous files in CMS (that is, files with 


missing records), the input buffer will be filled with the appropriate 
humber of bytes. Be aware that the flag byte in the FSCB may not 
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reflect whether the input buffer contains generated data items fron 
RDBUF. 


FSCBBUFF: The buffer address, specified in the BUFFER option, indicates 
the label of the buffer from which the record is to be written or into 
which the record is to be read. You should always supply a buffer large 
enough to accommodate the longest record you expect to read or write. 
This field must be specified, either in the FSCB, or on the FSREAD or 
FSWRITE macro instruction. 


FSCBSIZE: This field indicates the number of bytes that are read or 
written with each read or write operation. The default value is 0. If 
the buffer that you use represents the full length of the records you 
are going to be reading or writing, you can use the BSIZE option to set 
this field egual to your buffer length; when you are writing 
variable-length records, use the BSIZE operand to indicate the length of 
each record you write. This field must be specified. 


FSCBFV: This two-character field indicates the record format (RECFM) of 
the file. The default value is F (fixed). 


FSCBFLG: The flag byte is X'20" indicating an extended FSCB generated 
when the FORM=E option is coded on the FSCB macro instruction. 


FSCBNOIT: For an FSCB without the FORM=E option, this field contains the 
number of whole records that are to be read or written in each read or 
write operation. You can use the NOREC option with the BSIZE option to 
block and deblock records. 


For an FSCB generated with the FORM=E option, the FSCBANIT field 
contains the number of whole records to be read or written. The 
FSCBNOIT field is reserved. 


FSCBNORD: Following a read operation, this field contains the number of 
bytes that were actually read, so that if you are reading a 
variable-length file, you can determine the size of the last record 
read. The FSREAD macro instruction places the information from this 
field into register 0. 


FSCBAITN: The alternate record or item number indicates the relative 
record number of the next record to be read or written in an extended 
FSCB format. See the description of the FSCBITNO field for the usage of 
this field. 


FSCBANIT: This field contains the alternate number of whole records in 
an extended FSCB format. See the description of the FSCBNOIT field for 
the usage of this field. 


FSCBWPTR: The FSPOINT macro instruction uses this field to contain the 
alternate write pointer for an extended FSCB during a POINT operation. 


FSCBRPTR: The FSPOINT macro instruction uses this field to contain the 
alternate read pointer for an extended FSCB during a POINT operation. 


Using the FSCB 


The following example shows how you might code an FSCB macro instruction 
to define various file and buffer characteristics, and then use the sane 
FSCB to refer to different files: 
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FSREAD ‘INPUT FILE A1',FSCB=COMMON,FORM=E 
FSWRITE ‘OUTPUT FILE A1',FSCB=COMMON, FORMN=E 


COMMON FSCB BUFFER=SHARE, RECFM=V,BSIZE=200, FORM=E 
SHARE DS CL200 


In the above example, the fileid specifications on the FSREAD and 
FSWRITE macro instructions modify the FSCB at the label COMMON each time 
a read or write operation is performed. You can also modify an FSCB 
directly by referring to fields by a displacement off the beginning of 
the FSCB; for example: 


NVC FSCB+8, =CL8'NEWNAME! 


moves the name NEWNAME into the filename field of the FSCB at the label 
FSCBFN. 


As an alternative, you can use the FSCBD macro instruction to 
generate a DSECT and refer to the labels in the DSECT to modify the 
FSCB; for example: 


LA R5,INFSCB 
USING FSCBD,R5 


MVC FSCBFN, NEWNAME 


INFSCB FSCB ‘INPUT TEST A1",FORM=E 
NEWNAME DC CL8"OUTPUT® 
FSCBD 


In the above example, the MVC instruction places the filename OUTPUT 
into the FSCBFN (filename) field of the FSCB. The next time this FSCB is 
referenced, the file OUTPUT TEST is the file that is manipulated. 


Reading and Writing CMS Disk Files 


CMS disk files are sequential files; when you use CMS macros to read and 
write these files, you can access them sequentially with the FSREAD and 
FSWRITE macros. However, you may also refer to records in a CMS file by 
their relative record numbers, so you can, in effect, access records 
using a direct access method. 


If you know which record you want to read or write, you can specify 
the RECNO option on the FSCB macro instruction, or on the FSOPEN, 
FSREAD, or FSWRITE macro instructions. When you use the RECNO option on 
the FSCB macro instruction, you must specify it as a self-defining tern; 
for the FSOPEN, FSREAD, or FSWRITE macro instructions, you may specify 
either a self-defining term, as: 


WRITE FSWRITE FSCB=WFSCB,RECNO=10, FORM=E 
Or using register notation, as follows: 


WRITE FSWRITE FSCB=WFSCB,RECNO=(5) , FORM=E 
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where register 5 contains the record number of the record to be read. 


When you want to access files sequentially, the FSCBITNO field of the 
FSCB must be O for an FSCB without the FORM=E option; for an extended 
FSCB, the FSCBAITN field must be 0. This is the default value. When you 
are reading files with the FSREAD macro instruction, reading begins with 
record number 1. When you are writing records to an existing file with 
the FSWRITE macro, writing begins following the last record in the file. 


To begin reading or writing files sequentially beginning at a 
specific record number, you must specify the RECNO option twice: once to 
specify the relative record number at which you want’ to begin reading, 
and a second time to specify RECNO=0 so that reading or writing will 
continue sequentially beginning after the record just read or written. 
You can specify the RECNO option on the FSREAD or FSWRITE macro 
instruction, or you may change the FSCBITNO or FSCBAITN field in the 
FSCB for the file, as necessary for the FSCB forn. 


For example, to read the first record and then the 50th record of a 
file, you could code the following: 


READ1 FSREAD FSCB=RFSCB,FORM=E 
FSWRITE FSCB=WFSCB, FORMN=E 
LA 5,RFSCB 
USING FSCBD,5 
MVC FSCBAITN,=F'50Q' 
READ5O FSREAD FSCB=RFSCB, FORM=E 
FSWRITE FSCB=WFSCB, FORM=E 


RFSCB FSCB "INPUT FILE A1', BUFFER=COMMON, BSIZE=120, FORM=E 
WFSCB FSCB "OUTPUT FILE A1',BUFFER=COMMON, BSIZE=120,FORM=E 
COMMON DS CL120 

FSCBD 


In this example, the statements at the label READ1 write record 1 fron 
the file INPUT FILE A1to the file OUTPUT FILE A1. Then, using the 
DSECT generated by the FSCBD macro, the FSCBITNO field is changed 
because an extended FSCB is being used 


FSCBAITN field is changed because an extended FSCB is being used and 
record 50 is read from the input file and written into the output file. 


READING AND WRITING VARIABLE-LENGTH RECORDS: When you read or write 
variable-length records, you must specify RECFM=V either in the FSCB for 
the file or on the FSWRITE or FSREAD macro instruction. The read/write 
buffer should be large enough to accommodate the largest record you are 


going to read or write. 


To write variable-length records, use the BSIZE= option on the 
FSWRITE macro instruction to indicate the record length for each record 
you write. When you read variable-length records, register 0 contains, 
on return from FSREAD, the length of the record read. 


The following example shows how you could read and write a 
variable-length file: 


READ FSREAD ‘DATA CHECK A1*, BUFFER=SHARE, BSIZE=130, ERROR=OUT, 
FORN=E 
FSWRITE ‘COPY DATA A1',BUFFER=SHARE, BSIZE=(0) , FORM=E 
B READ 
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When you update files of variable-length records, the replacement record 
must be the same length as the original record. An attempt to write a 
record shorter or longer than the original record results in truncation 
of the file at the specified record number. No error return code is 
given. 


End-of-File Checking 


You can specify the ERROR= operand with the FSREAD or FSWRITE macro 
instruction, so that an error handling routine receives control in case 
of an error. In CMS, when an end of file occurs during a read request, 
it is treated as an error condition. The return code is always 12. If 
you specify an error handling routine on the FSREAD macro instruction, 
then the first thing this routine can do is check for a 12 in register 
15. 


Your error handling routine may also check for other types of errors. 
See the macro description in VM/SP CMS Command and Macro Reference for 
details on the possible errors and the associated return codes. 


Opening and Closing Files 


Usually, CMS opens a file whenever an FSREAD or fFSWRITE macro 
instruction is issued for the file. When control returns to CMS from a 
calling program, all files accidentally left open are closed by CMS, so 
you do not have to close files at the end of a progran. 


For a minidisk in 1K-, 2K-, or 4kK-byte block format, a file may be 
open for concurrent read and write operations, and an FSCLOSE need not 
be issued when switching from reading to writing, or vice versa. For 
example: 


LA 3,2 
READ FSREAD FSCB=UPDATE, RECNO=(3) , ERROR=READERR, FORM=E 


FSWRITE FSCB=UPDATE, RECNO= (3) , ERROR=WRITERR, FORM=E 
LA 3, 1 (3) 
B READ 


UPDATE FSCB ‘UPDATE FILE A1', BUFFER=BUF1,BSIZE=80, FORM=E 


When you are running long running applications or running 
disconnected, include several FSCLOSE macros to each file referenced. 
This insures that changes to the file are reflected on the disk in the 
event that the user is forced off the system. This consideration is 
important when running on 1K, 2K, or 4K disks since the disk directory 
is not updated until all of the files on the disk are closed. 


If you want to read andwrite records from the same file on an 
800-byte block format tminidisk, you must issue an FSCLOSE macro 
instruction to close the file whenever you switch from reading to 
writing. For example; 
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LA 3,2 
READ FSREAD FSCB=UPDATE, RECNO=(3) , ERROR=READERR 
FSCLOSE FSCB=UPDATE 


FSWRITE FSCB=UPDATE, RECNO= (3) , ERROR=WRITERR 
FSCLOSE FSCB=UPDATE 

LA 3,1(3) 

B READ 


UPDATE FSCB ‘UPDATE FILE A1',BUFFER=BUF1,BSIZE=80 


To execute a loop to read, update, and rewrite records, you must read 
a record, close the file, write a record, close the file, and _ so on. 
Since closing a file repositions the read pointer to the beginning of 
the file and the write pointer at the end of the file, you must specify 
the relative record number (RECNO) for each read and write operation. In 
the above example, register 3 is used to contain the relative record 
number. It is initialized to begin reading with the second record in 
the file and is increased by one following each write operation. 


When you use an EXEC to execute a program to read or write a file, 
the file is not closed by CMS until the EXEC completes execution. 
Therefore, if you read or write the same file more than once during the 
EXEC procedure, you must use an FSCLOSE macro instruction to close the 
file after using it in each program, or use the PSOPEN macro instruction 
to open it before each use. Otherwise, the read or write pointer is 
positioned as it was when the previous program completed execution. 


CREATING NEW FILES: When you want to begin writing a new file using CMS 
data management macros, there are two ways to ensure that the file you 
want to create does not already exist. One way is to issue the FSSTATE 
macro instruction to verify the existence of the file. 


A second way to ensure that a file does not already exist is to issue 
an FSERASE macro instruction to erase the file. If the file does not 
exist, register 15 returns with a code of 28. If the file does exist, it 
is erased. 


See Figure 25 for an illustration of a sample program using CMS data 
Management macros. 


CMS MACROS FOR TERMINAL COMMUNICATIONS 


There are four CMS macros’ you can use to write interactive, 
terminal-oriented programs. They are RDTERM, WRITERM, LINEDIT, and WAITT. 
RDTERM and WRTERM only require a read/write buffer for sending and 
receiving lines from the terninal. The third, LINEDIT, has a 
substitution and translation capability. 


When you use the WRTIERM macro to write a line to your terminal you 
can specify the actual text line in the macro instruction, for example: 


DISPLAY WRTERM ‘GOOD MORNING! 


You can also specify the message text by referring toa buffer that 
contains the message. 


The RDTERM macro accepts a line from the terminal and reads it into a 
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LINE SOURCE STATEMENT 


| °* The program might be invoked with a parameter list in the format 


[ progname INPUT FILE A1 OUTPUT FILE Al. This line is placed ina 
[ parameter list by CMS routines and addressed by register 1 


Le _ (see note 2). 


pean 


| which indicates an end—of—file condition. If it is the end of 
[ the file, the program exits; otherwise, it writes an error 


{ message. 


| *® The dots in the LINEDIT macro are substituted, during execution, 


| | 
l Sass | 
| BEGIN CSECT a | 
| PRINT NOGEN | 
USING *, 12 ESTABLISH ADDRESSABILITY | 
{ LR 12,15 | 
{ ST 14,SAVE _ | 
LA 2,8(,1) R2=ADDR OF INPUT FILEID IN PLIST 2 { 
i LA 3,32(,1) R3=ADDR OF OUTPUT FILEID IN PLIST | 
|* DETERMINE IF INPUT FILE EXISTS | 
I FSSTATE (2), ERROR=ERR1, FORM=E | 
|* | 
{* READ A RECORD FROM INPUT FILE AND WRITE ON OUTPUT FILE - | 
| RD FSREAD (2) , ERROR=EOF, BUFFER=BUFF1,BSIZE=80,FORM=E a | 
; FSWRITE (3), ERROR=ERR2, EUFF FR=BUFF1,BSIZE=80, FORM=E | 
| B RD LOOP BACK FOR NEXT RECORD 
|* | 
|* COME HERE IF ERROR READING INPUT FILE _ : | 
| EOF c 15,=F'12! END OF FILE ? ss | 
BNE  ERR3 ERROR IF NOT | 
I LA 15,0 ALL O.K. — ZERO OUT R15 | 
| B EXIT GO EXIT | 
|* IF INPUT FILE DOES NOT EXIST | 
[ERR1 WRTERM 'FILE NOT FOUND', EDIT=YES | 
i B EXIT | 
|* | 
|* IF ERROR WRITING FILE "= | 
{ ERR2 LR 10,15 SAVE RET CODE IN REG 10 Ss | 
1 LINEDIT TEXT="ERROR CODE .... IN WRITING FILE',SUB=(DEC, (10) ) | 
B EXIT l 
|* | 
1* IF READING ERROR WAS NOT NORMAL END OF FILE — | 
| ERR3 LR 10,15 SAVE RET CODE IN REG 10 Ss 
) LINEDIT TEXT="ERROR CODE .... IN READING FILE',SUB=(DEC, (10)) | 
|* | 
J EXIT L 14, SAVE LOAD RETURN ADDRESS 1 
| BR 14 RETURN TO CALLER " 
| * | 
| BUFF1 DS CL80 
{SAVE DS F | 
| END | 
\ l 
iNotes: | 

{ 

| 

| 

| 

\ 

| 

| 

| 

| 

{ 

I 

| 

l 

| 

| 

l 

| 


{ with the decimal value in register 10. 


one of the words entered on the command line. Thus, 8 bytes 
past register 1 is the beginning of the input fileid; 24 bytes 
beyond that is the beginning of the second fileid. 

‘The FSREAD and FSWRITE macros cause the files to be opened; no 
open macro is necessary. CMS routines close all open files when 
a program completes execution (except CMS EXEC files). 

| ® The return code in register 15 is tested for the value 12, 


a 
Figure 25. A Sample Listing of a Program that Uses CMS Macros 
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buffer you specify. You could use the RDTERM and WRTERM macros together, 
as follows: 


WRITE WRIERM ‘ENTER LINE* 
READ RDTERM BUFFER 
LR 3,0 


REWRITE WRIERM BUFFER, (3) 


BUFFER DS CL130 


In this example, the WRTERM macro results in a prompting message. Then 
the RDTERM macro accepts a line from the terminal and places it in the 
buffer BUFFER. The length of the line read, contained in register 0 on 
return from the RDTERM macro, is saved in register 3. When you specify 
a buffer address on the WRTERM macro instruction, you must specify the 
length of the line to be written. Here, register notation is used to 
indicate that the length is contained in register 3. 


The LINEDIT macro converts decimal and hexadecimal data into EBCDIC, 
and places the converted value into a specified field in an output line. 
There are list and execute forms of the macro instruction, which you can 
use in writing reentrant code. Another option allows you to write lines 
to the offline printer. The LINEDIT macro is described, with examples, 
in VM/SP CMS Command and Macro Reference. Figure 25 shows how you might 
use the LINEDIT macro to convert and display CMS return codes. 


The WAITT (wait terminal) macro instruction can help you _ to 
synchronize input and output to the terminal. If you are executing a 
program that reads and writes to the terminal frequently, you may want 
to issue a WAITT macro instruction to halt execution of the progran 
until all terminal I/O has completed. 


CMS MACROS FOR UNIT RECORD AND TAPE I/0 


CMS provides macros to simplify reading and punching cards (RDCARD and 
PUNCHC), and creating printer files (PRINTL). When you use either the 
PUNCHC or PRINTL macros to write or punch output files while a program 
is executing, you should remember to issue a CLOSE command for your 
virtual printer or punch when you are finished. You can do this either 
after your program returns control to CMS, by entering: 


cp close e 
cp close d 


Or, you can set up a parameter list with the command line CP CLOSE E or 
CP CLOSE D and issue an SVC 202. 


The tape control macros, RDTAPE, WRTAPE and TAPECTL, can read and 
write CMS files from tape, or control the positioning of a tape. 


INTERRUPTION HANDLING MACROS 


You can set up routines in your programs to handle interruptions caused 
by I/O devices, by SVCs, or by external interruptions using the HNDINT, 
HNDSVC, or HNDEXT macro instructions. 
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With the HNDINT macro instruction, you can specify addresses that are 
to receive control when an interruption occurs for a specified device. 
If the WAIT option is used for a device specified in the HNDINT macro 
instruction, then the interruption handling routine specified for the 
device does not receive control until after the WAITD macro instruction 
is issued for the device. 


You can use the HNDSVC macro instruction to trap supervisor call 
instructions of particular numbers, if, for example, you want to perforn 
some additional function before passing control or you do not want any 
SVCs of the specified number to be executed. 


The CP EXTERNAL command simulates external interruptions in your 
virtual machine; if you want to be able to pass control to a particular 
internal routine in the event of an external interruption, you can use 
the HNDEXT macro instruction. 


Updating Source Programs Using CMS 


As you test and modify programs, you may want to keep backup copies of 
the source programs. Then you can always return to a certain level of a 
program in case you have an error. CMS provides several approaches to 
the problem of program backup: the method you choose depends on the 
complexity of your project, the changes you want to make, and the size 
of your programs. 


The simplest method is to make a copy of the current source file 
under a new name. You can do this using either the COPYFILE command or 
the CMS editor. If you use the COPYFILE command, your command line 
might be: 


copyfile account assemble a oldacct assemble a 


Then, you can use the editor to modify ACCOUNT ASSEMBLE; the file 
OLDACCT ASSEMBLE contains your original source file. 


You can make a copy of your source file using the CMS editor 
directly. For example, if you issue: 


edit account assemble 
EDIT: 
fname newacct 


then any subsequent changes you make to the file ACCOUNT ASSEMBLE are 
written into the file NEWACCT ASSEMBLE. When you issue a FILE or SAVE 
subcommand, your source file remains intact. 


After your changes to the source program have been tested, you can 
replace the source file with your new copy. 


THE UPDATE PHILOSOPHY 


While the procedures outlined above for modifying programs are suitable 
for many applications, they may not be adequate ina situation where 
several programmers are applying changes to the same source code. These 
procedures also have the drawback of not providing you with a record of 
what has been changed. After using the editor, you do not have a record 
of the lines that have been deleted, added, replaced, and so on, unless 
you manually add comments to the code, insert special characters in the 
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serialization column, or use some technigue that records program 
activity. 


The UPDATE command provides a way for you to modify a source progran 
without affecting the original, and it produces an update log, 
indicating the changes that have been made. Moreover, it also has the 
capability of combining multiple updates at one time, so that changes 
made by different programmers or changes made at different times can be 
combined into a Single output file. 


The UPDATE command is a basic element of the entire VM/SP updating 
scheme and is used by system programmers who maintain VM/SP at your 
installation. Although the input filetypes used by the UPDATE command 
default to ASSEMBLE file characteristics, the UPDATE command is not 
limited to assembler language programs, nor is it limited to. systen 
programming applications. You can use it to modify and update any 
fixed-length, 80-character file that does not have data in columns 73 
through 80. 


UPDATE FILES 


A simple update involves two input files: 
e The source file, which is the program you want to update 


e An update file, containing control statements that describe the 
changes you want to make 


The control statement file usually has a filetype of UPDATE. For 
convenience, you can give it the same filename as your source file. For 
example, if you want to update the file SAMPLE ASSEMBLE, you would 
create a file named SAMPLE UPDATE. 


To apply the changes in the update file, you issue the command: 
update sample 


The default values used by the UPDATE command are filetypes of ASSEMBLE 
and UPDATE for the source and update files, respectively. If you are 
updating a COBOL source program named READY COBOL with an update file 
named UPDATE READY, you would issue the command: 


update ready cobol a update ready a 


After an UPDATE command completes processing, the input files are not 
changed; two new files are created. One of them contains the updated 
source file, with a filename that is the same as the original source 
file but preceded by a dollar’ sign ($). Another file, containing a 
record of updates is also created; it has a filename that is the same as 
the source file and a filetype of UPDLOG. For example: 


Source files Qutput files 
SAMPLE ASSEMBLE $SAMPLE ASSEMBLE 
SAMPLE UPDATE SAMPLE UPDLOG 
READY COBOL S$READY COBOL 
UPDATE READY READY UPDLOG 


Now, you can assemble or compile the new source file created by the 
UPDATE command. 
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UPDATE Control Statements 


The control statements used by the UPDATE command are similar to those 
used by the OS IEBUPDTE utility program or the DOS MAINT program UPDATE 
function. 


Each UPDATE statement must have the characters ./ in columns one and 
two, followed by one or more blanks. The statements are described 
below, with examples. 


SEQUENCE Statement: This statement tells the UPDATE command that you 
want to number or renumber the records ina file. Sequence numbers are 
written in columns 73 through 80. For example, the statement: 


-f S 1000 


indicates that you want sequence numbering to be done, in increments of 
1000, with the first statement numbered 1000. The SEQUENCE statement is 
convenient if you want to apply updates toa file that does not already 
have sequence numbers. In this case, you may want to use the REP 
(replace) option of the UPDATE command, so that instead of creating a 
new file ($filename), the original source file is replaced: 


update sample (rep 
INSERT Statement: This statement precedes new records that you want to 


add to a source file. The INSERT statement tells the UPDATE command 
where to add the new records. For example, the lines: 


-/ I 1600 
TEST2 TM HOLIDAY,X'02!' HOLIDAY? 
BNO VACATION NOPE...VACATION 


result in the two lines of code being inserted into the output file 
following the statement numbered 00001600. The inserted lines are 
flagged with asterisks in columns 73 through 80. The INSERT statement 
also allows you to request that new statements be sequenced; see 
"Sequencing Output Records." 


DELETE Statement: This statement tells the UPDATE command which records 
you want to delete from the source file. If your UPDATE file contains: 


-f D- 2500 


® 


then only the record 00002500 is deleted. If the file contains 
-f D 2500 2800 


then all the statements from 2500 through 2800 are deleted from the 
source file. 


REPLACE Statement: The REPLACE statement allows you to replace one or 
more records in the source file. It precedes the new records you want 
to add. It is a combination of the DELETE and INSERT statements. For 
example, the lines 


-/ R 38000 38500 


PLIST DS OD 
DC CL8'TYPE! 
DC CLS! ' 
DC CL8"'FILE' 
DC CL8'A1' 
DC SX'FF!* 
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replace existing statements numbered 38000 through 38500 with the new 
lines of code. AS with the INSERT statement, new lines are not 
automatically resequenced. 


COMMENT Statement: Use this statement when you want to place comments in 
the update log file. For example, the line: 


-/ * Changes by John J. Programmer 


is not processed by the UPDATE command when it creates the nhew source 
file, but it is written into the update log file. 


SEQUENCING OUTPUT RECORDS 


The UPDATE command expects source files to have sequence numbers in 
columns 73 through 80. If you use the SERIAL subcommand of the CMS 
editor to sequence your files, the sequence numbers are usually written 
in columns 76 through 80; columns 73 «through 75 contain a 
three-character identifier which is usually the first three characters 
of the filename. If you want an eight-character sequence number, you 
must use the subconmmand: 


serial all 


prior to issuing a FILE or SAVE subcommand when you are editing the 
file. Or, you can create an UPDATE file with the single record: 


-/ Ss 
and issue the UPDATE command to sequence the file. 

If you use the UPDATE command with a file that has been sequenced 
using the CMS editor's default values, you must use the NOSEQ8 option. 
Otherwise, the UPDATE command cannot process your input file. The 
command: 


update sample (noseq8 


tells UPDATE to use only columns 76 through 80 when it looks’ for 
sequence numbers. 
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Figure 26 shows the four files involved in a simple update, and their 
contents. 


The Source File, SAMPLE ASSEMBLE 
a te RR ge ge ee eS aa A a ee ee ee 


| SAMPLE CSECT 00000100 | 
USING SAMPLE, R12 00000200 | 
LR R12,R15 00000300 l 
| ST R14, SAVRET 00000400 | 
| LINEDIT TEXT="PLEASE ENTER YOUR NAME! 00000500 | 
| RDTERM NAME 00000600 l 
l LINEDIT TEXT="PLEASE ENTER YOUR AGE! 00000700 
| RDTERM AGE 00000800 
| LINEDIT TEXT="HI, .......---, YOU JUST TOLD ME YOU ARE .....',x00000900 r 
| SUB= (CHARA, NAME, CHARA, AGE) , RENT=NO 00001000 | 
| L R14, SAVRET 00001100 | 
| BR R14 00001200 | 
l EJECT 00001300 | 
| NAME DC CL130* * 00001400 l 
| AGE DC CL130' ! 00001500 r 
| SAVRET DC Ftor 00001600 
| REGEOU 00001700 l 
l END 00001800 | 


Mr 


| 


The Update File, SAMPLE UPDATE 
S$. 


| ./ * REVISION BY DLC SAM00010 l 
1 -/ R 500 SAM00020 i 
LINEDIT TEXT="WHAT*'*S YOUR NAME?', DOT=NO SAM00030 | 
| -/ P 700 1000 SAMO004O | 
LINEDIT TEXT="HI, .....-----, ENTER THE DOCNAME', xSAM00050 l 
| SUB= (CHARA, NAME) SAM00060 l 
| RDTERM NAME SAM00070 l 
l MVC DOCFN, NAME SAM00080 l 
| LA 1,PLIST SAM00090 
| SVC 202 SAM00100 | 
r DC AL4 (ERROR) SAM00110 | 
| RETURN EQU- * SAM00120 
| -/ I 1200 SAM00130 l 
| ERROR EQU ot SAM00140 | 
r WRTERM "FILE NOT FOUND! SAM00150 l 
| B RETURN SAM00160 | 
| -/ D 1500 SAM00170 l 
| ./ I 1609 SAM00180 
| PLIST DS OD SAM00190 
l Dc CL8'TYPE! SAM00200 l 
| DOCFN DC CL8" ' SAM00210 
| DC CL8'FILE! SAM00220 l 
l DC CL8"A1" SAM00230 l 
| DC SX'FF! SAM00240 l 
CS eee | 


Figure 26. Updating Source Files with the UPDATE Command (Part 1 of 2) 
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The Source File, 


SAMPLE ASSEMBLE 


Ce 


The Update File, 


i 
| 
| 
[ 
| 
| 
I 
| 
[ 
| 
1 
| 
| 
I 
| 
| 
| 
| 
1 
| 
| 
| 
| 
{ 


SAMPLE 


CSECT 


USING SAMPLE, R12 


LR 
sT 


R12,R15 


R14, SAVRET 
LINEDIT TEXT="PLEASE ENTER YOUR NAME! 


RDTERM NAME 


LINEDIT TEXT="PLEASE ENTER YOUR AGE* 


RDTERM 


LINEDIT TEXT="HI, 
SUB= (CHARA, NAME, CHARA, AGE) , RENT=NO 
R14, SAVRET 


REGEQU 
END 


AGE 


R14 


CL130* * 
CL130' * 
Fro! 


SAMPLE UPDATE 


-/ * REVISION BY DLC 


-/ RB 500 
-/ PB 700 


RETURN 
-/ I 1209 
ERROR 


-/ D 1500 
-/ I 1609 
PLIST 


DOCFN 


LINEDIT TEXT="WHAT''S YOUR NAME?',DOT=NO 


1000 


LINEDIT TEXT='RI, 
SUB= (CHARA, NAME) 


RDTERM 
MVC 
LA 
SVC 20 
DC 
EQU 


EQU 
WRTERM 
B 


NAME 


DOCFN, NAME 


1,PLIST 
2 


AL4 (ERROR) 


* 


x 


"FILE NOT FOUND! 


RETURN 


OD 
CL8'TYPE' 
CLet% 
CL8' FILE! 
CLAB'A1" 
SX'FF!* 


ENTER THE DOCNAME’, 


00000100 
00000200 
00000300 
00000800 
00000500 
00000600 
00000700 
00000800 


YOU JUST TOLD ME YOU ARE .....*,x00000900 


00001000 
00001100 
00001200 
00001300 
00001400 
00001500 
00001600 
00001700 
00001800 


SAM00010 
SAM00020 
SAmN00030 
SAM00040 


xSAM00050 


SAMO0060 
SAN00070 
SAN00080 
SAM00090 
SAM00100 
SAM00110 
SAM00120 
SAM00130 
SAM00140 
SAM00150 
SAM00160 
SAM00170 
SAN00180 
SAM00190 
SAM00200 
SAN00210 
SAM00220 
SAMN00230 
SAHN00240 


a NN NE | 


Figure 26. 
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Updating Source Files with the UPDATE Command (Part 2 of 2) 


The INSERT and REPLACE statements allow you to control the numbering 
increment of records that you add to a source file. Notice, in Figure 
26, that inserted records have the character string '*****4#*#! jin 
columns 73 through 80. If you want sequence numbers on the inserted 
records, you must do two things: 


1. Use the INC option on the UPDATE command line. If you use the CTL 
option, you do not have to specify the INC option. The CTL option 
is described below, under "Multiple Updates." 


2. Include a dollar sign ($) on the INSERT or REPLACE statement, 
optionally followed by operands indicating how the records should 
be sequenced. 


For example, to sequence the records added in Figure 26, the control 
statements would appear as: 


-/ R 500 $ 
-/ R 700 1000 $ 
-/ I 1200 $ 
-/ I 1600 $ 


and you would issue the UPDATE command: 
update sample (inc 
The UPDATE command sequences inserted records by increments of 10. 
If you want to control the numbering, for example, if you need to insert 
more than 10 statements between two existing statements, you can specify 


an alternate sequencing scheme: 


-/ I 1800 $ 1805 5 


Records introduced following this INSERT statement are numbered 
00001805, 00001810, 00001815, and so on. (If the NOSEQS8 option is in 
effect, then the records would be XxXx01805, XXx01810, and so on, where 
XXX is the three-character identifier used in columns 73 through 75.) 


MULTIPLE UPDATES 


If you have several UPDATE files to apply to the same source, you may 
apply them ina series of UPDATE commands. For example, if you have 
updates named FICA UPDTUP1, FICA UPDTUP2, and FICA UPDTUP3 to apply to 
the source file FICA PLIOPT, you could do the following: 
1. Update the source file with TEST1 UPDATE: 
update fica pliopt a fica updtup1 


2. Update the source file produced by the above command with the TEST2 
UPDATE: 


update $fica pliopt a fica updtup2 
3. Update the new source file with TEST3: 


update $$fica pliopt a fica updtup3 
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This final UPDATE command produces the file $$$FICA PLIOPT, which is now 
the fully updated source file. This method is cumbersome, however, 
particularly if you have many updates to apply and they must be applied 
in a particular order. Therefore, the UPDATE command provides a 
multilevel update scheme, which you can use to apply many updates at one 
time, in a specified order. 


To apply multilevel updates, you must have a control file, which by 
convention has a filetype of CNTRL and a filename that is the same as 
the source input file. Therefore, to apply the three update files to 
FICA PLIOPT, you should create a file named FICA CNTRL. 


The Control File 


A control file is actually a list: it does not contain any actual update 
control statements (INSERT, DELETE, and so on), but rather it indicates 
what update files should be applied, and in what order. In the case of 
a multilevel update, all the update files must have the same filename as 
the source file. Therefore, only the filetypes need be specified in the 
control file to uniquely identify the update file. In fact, if all your 
update files have filetypes beginning with the characters UPDT, you need 
only specify the unique part of the filetype. The control file for FICA 
PLIOPT, named FICA CNTRL, may typically look like the following: 


TEXT MACS PLILIB 
FICA3 UP3 
PICA2 UP2 
FICA1 UP1 


The first record in the control file must be a MACS’ record. The 
second field in this record must be "MACS", and it may be followed by up 
to eight macro library nanes. Every record in the control file nust 
have an “update level identifier;" in this example, the update level 
identifiers are TEXT on the MACS record, FICA1 for the UP1 record, and 
So on. The update level identifier may have a maximum of five 
characters. See the "STK option" for more details about the "update 
level identifier". 


The UPDATE command only uses the MACS record and the update level 
identifier under special circumstances. These are described later, 
under "VMFASM EXEC Procedure", For now, you only need to know that 
these things must be in a control file in order for the UPDATE command 
to execute properly. 


To update FICA PLIOPT, then, you would issue the UPDATE command as 
follows: 


update fica pliopt (ctl 


When you use the CTL option, and you do not specify the name of a 
control file, the UPDATE command looks for aocontrol file with the 
filetype of CNTRL anda filename that is the same as the source file. 
From the control file, it reads the filetypes of the updates to be 
applied. In this example, it searches for the file FICA UPDTUP1 and if 
found, applies the updates; then UPDATE searches for FICA UPDTUP2, and 
applies those updates, if any. Last it searches for FICA UPDTUP3, and 
applies those updates. 


Notice that the updates are applied from the bottom of the control 
file, toward the top. This becomes important when an update is 
dependent on a previous update. For example, if you add some lines to a 


286 IBM VM/SP CMS User's Guide 


file in FICA UPDTUP1, then modify one of those lines in FICA UPDTUP2, it 
is important that UPDTUP1 was applied first. 


ALTERNATE WAYS OF SPECIFYING MULTILEVEL UPDATE FILES: The example above, 
showing FICA CNTRL and UPDTxxxx files, illustrates a naming scheme using 
the UPDATE command defaults. You can override the default filetypes for 
the control file's filename and filetype, as well as filetypes for the 
update files. 


If you name a control file GROUPA CNIRL, for example, you can specify 
the name of the control file on the UPDATE command line: 


update fica pliopt a groupa cntrl (ctl 


Similarly, if your update files have unique filetypes, you am|ust 
specify the entire filetype in the control file. If your updates to 
FICA PLIOPT are named FICA TEST1, FICA TEST2, and FICA TEST3, your 
control file may look like the following: 


TEXT MACS PLILIB 
FICA3 TEST3 
FICA2 TEST2 
FICA1 TEST1 


Regardless of the filetypes you choose, however, the filenames must 
always be the same as the filename of the input source file. 


AUX Files 


The two levels of update processing shown so far may be adequate for 
your applications. There is, however, an additional level, or step, in 
the update structure that the VM/SP procedures use and which you may 
want to use also. 


These techniques may be useful when you have more than one set of 
updates to apply to a source program. For example, you may have two 
groups of programmers who are working on different sets of changes for 
the same source file. Each group may create several update files, and 
have a unique control file. When you combine these changes, you could 
create one control file, or you can use what are known as auxiliary 
control files. 


The updating structure for auxiliary control files is based on 
conventions for assigning filenames and filetypes. If a control file 
contains an entry that begins with the characters ‘AUX', the UPDATE 
command assumes that the file ‘fn AUXnnnn' contains a list of filetypes, 
not UPDATE control statements. For example, if the file SAMPLE ASSEMBLE 
is being updated with a control file that contains the record: 


TEST1 AUXLIST 
then SAMPLE AUXLIST does not contain UPDATE control statements; it 
contains entries indicating the filetypes of the update files, all of 
which must have the same filename, SAMPLE. 
Let's expand the example to see how this structure works. We have 
the source file, SAMPLE ASSEMBLE. The file SAMPLE CNTRL contains the 
entries; 


TEXT MACS 
3676 AUXLIST 
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The file, SAMPLE AUXLIST may look like the following: 


TEST1 
FIXLOOP 
BYPASS 


The files: 


SAMPLE TEST1 
SAMPLE FIXLOOP 
SAMPLE BYPASS 


all contain UPDATE control statements (INSERT, DELETE, and so on) that 
are to be applied to the file SAMPLE ASSEMBLE. As with control file 
processing, the updates are applied from the bottom of the AUX file, so 
that the updates in SAMPLE BYPASS are applied first, then the updates in 
SAMPLE FIXLOOP, and so on. For an illustration of a set of update 
files, see Figure 27. 


Since the updating scheme uses only filetypes to uniquely identify 
update files, it is possible to use the same control file to update 
different source input files. For example, using the control file 
REPORT CNTRL shown in Figure 27, you issue the command: 


update fica pliopt a report cntrl (ctl 


The UPDATE command begins searching for updates to apply to FICA PLIOPT, 
based on the entries in REPORT CNTRL: it searches for FICA AUXFIX, which 
May contain entries pointing to update files; then it searches for FICA 
UPDTREP1, and so on. 


As long as all updates and auxiliary files associated with a source 
file have the same filename as the source file, the updates are uniquely 
identifiable, so the same control file can be used to update various 
source files. VWM/SP takes advantage of this capability in its own 
updating procedures. By maintaining strict naming conventions, updates 
to various CP and CMS modules are easily controlled and identified. 


A control file may point to many ADX files in addition to many UPDT 
files. You can modify a control file when you want to control which 
updates are applied to a program, or you may have several control files, 
and specify the name of the control file you want to use on the UPDATE 
command line. There is a lot of flexibility in the UPDATE command 
processing; you can implement procedures and conventions for your 
individual applications. 


PREFERRED LEVEL UPDATING: There may exist more than one version of an 
update, each applicable to different versions of the same module. For 
example, you may need one version of an update for an unmodified base 
source module, and another version of that update if that module has 
been modified by a program product. The AUX file that will be used to 
update a particular module must then be selected based on whether or not 
a program product modifies that module. The AUX files listing the 
updates applicable to modules modified by a program product are called 
"preferred AUX files" because they must be used if they exist rather 
than the mutually exclusive updates applicable to unmodified modules. 
Using this preferred AUX file concept, every module in a component can 
be assembled using the one cCNTRL file applicable to a user's 
configuration. 


A single AUX file entry in a CNTRL file can specify more’ than one 
filetype. The first filetype indicates a file that UPDATE uses only on 
one condition: the files that the second and subsequent filetypes 
indicate do not exist. If they do exist, this AUX file entry is ignored 
and no updating is done. The files that the second and subsequent 
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filetypes indicate are preferred because, if they exist, UPDATE does not 
use the file that the first filetype indicates. Usually, the preferred 
files appear later in the CNTRL file in a format that causes them to be 
used for updating. 


UPDATE scans each CNTRL file entry until a preferred filetype is 
found, until there are no more filetypes on the entry, or until a 
comment is found. (A character string that is less than four or more 
than eight characters is assumed to be a comment.) 


REPORT 
CNTRL 


MACS 
UP2 UPDTPROC 
LIST AUXLIST 

UP1 UPDTREP1 
AUXFIX 


REPORT 
UPDTPROC 


REPORT REPORT 
UPDTREP1 AUXFIX 


RTNB 
RTNA 
REPORT 
AUXLIST 
Ce REPORT REPORT 
RTNA RTNB 
REPORT REPORT 
FIXIN FIXOUT 


update report assemble a (ctl) 

UPDATING ‘REPORT ASSEMBLE A1' WITH ‘REPORT RTNA Al’. 
UPDATING WITH ‘REPORT RTNB Atl’, 

UPDATING WITH ‘REPORT UPDTREP1 Al’. 

UPDATING WITH ‘REPORT FIXOUT A1’. 

UPDATING WITH ‘REPORT FIXIN A1’. 

UPDATING WITH ‘REPORT UPDTPROC At’. 

R; i 

Figure 27. An Update with a Control File 
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THE VMNFASM EXEC PROCEDURE 


If you are an assembler language programmer and you are using the UPDATE 
command to update source programs you may want to use the VMFASM EXEC 
procedure. VMFASM is a VMN/SP update procedure; it invokes the UPDATE 
command and then uses the ASSEMBLE command to assemble the updated 
source file. 


If you are not an assembler language programmer, you may wish to 
create an EXEC similar to VMFASM that, instead of calling the assembler, 
calls one of the language compilers to compile an updated source file. 


When you use VMFASM, you specify the source filename, the filename of 
the control file, and optionally, parameters for the assembler. (The 
control file for VMFASM must have a filetype of CNTRL). For example, if 
you use the file GENERAL CNTRL to update SAMPLE ASSEMBLE, you enter the 
command line: 


vmfasm sample general 


The VMFASM EXEC uses the MACS card and the update level identifiers 
in the control file. It reads the MACS card to determine which macro 
libraries (MACLIBs) should ke searched by the assembler. Then VMFASM 
issues the GLOBAL MACLIB command specifying the MACLIBs you name on the 
MACS card. 


The update level identifier is used by VMFASM to name the output text 
file produced by the assembly. If the update level identifier of the 
most recent update file (the last one located and applied) is anything 
other than TEXT, the update level identifier is prefixed with the 
characters TXT to form the filetype. For example, if the file GENERAL 
CNTRL contains the records: 


TEXT MACS CMSLIB MYLIB OSMACRO 
UP2 FIX2 

UP1 FIX! 

TEXT AUXLIST 


and it is used to update the file SAMPLE ASSEMBLE, then: 


e If the file SAMPLE UPDTFIX2 is found and the updates applied, VMFASM 
hames the output text deck SAMPLE TXTUP2. 


e If the file SAMPLE UPDTFIX1 is found and the updates applied but no 
SAMPLE UPDTFIX2 is found, the text deck is named SAMPLE TXTUP1. 


e If the file SAMPLE AUXLIST is found but no SAMPLE UPDTFIX1 or SAMPLE 
UPDTFIX2 files are found, the text deck is named SAMPLE TEXT. 


e If no files are found, the update level identifier on the MACS card 
is used and the text deck is named SAMPLE TEXT. 


Since the UPDATE command works from the bottom of a control file 
toward the top, it is logical that the text filename be taken from the 
identifier of the last update applied. 


The VMFASM EXEC does not produce an updated source file, but leaves 
the original source intact. VMFASM produces two output files: a printed 
output listing that shows update activity; and the text file, which 
contains the update log as well as the actual object code. If you use 
the CMS LOAD command to load a text file produced by VMFASM, records 
from the update log are flagged as invalid, but the LOAD operation is 
not impaired. 

VMFASM renames all copies of the original fn TEXT deck on all R/W disks 
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to fn TXTOLD. The A-disk copy is erased, but copies on other read/write 
disks are not erased. The new fn TEXT or fn TXTxxxxx resides on the 
A-disk. 


THE STK OPTION: If you are interested in writing your own EXEC procedure 
to invoke the UPDATE command, you may wish to use the STK option. The 
STK (stack) option is valid only with the CTL option, and is meaningful 
only when the UPDATE command is invoked within an EXEC procedure. 


When the STK option is specified, UPDATE stacks the following data 
lines in the console stack: 


first line: * update level identifier 
second line: * library list from MACS record 


The update level identifier is the identifier of the most recent update 
that was found and applied. 


For example, an EXEC file that invokes the UPDATE command and then 
the ASSEMBLE command may contain the lines: 


UPDATE &1 ASSEMBLE * &2 CNTRL * (STK CTL 

GREAD VARS &STAR &TX 

EREAD VARS &STAR &1LIB1 &LIB2 &LIB3 &LIBY ELIBS &SLIB6 &LIB? ELIBB 
GLOBAL MACLIB &LIB1 &LIB2 &LIB3 &LIB4Y &LIB5 ELIB6 &LIB? &LIES 
GIF &TX NE TEXT FILEDEF TEXT DISK &1 TXT&ETX Al 

ASSEMBLE &1 &3 &4 &5 &6 &7 &8 6&9 

ERASE 3&1 ASSEMBLE 


If this EXEC is named UPASM EXEC and is invoked with the line: 
upasm fica fica (print noxref 
and the file FICA CNTRL contains: 
MAC MACS CMSLIB OSMACRO MYTEST 


FIX1 UPDTFIX 
LIST AUXLIST 


then the EXEC executes the following commands: 


UPDATE FICA ASSEMBLE * FICA CNTRL * (STK CTL 
GLOBAL MACLIB CMSLIB OSMACRO MYTEST 

FILEDEF TEXT DISK FICA TXTFIX1 Al 

ASSEMBLE $FICA (PRINT NOXREF 

ERASE $FICA ASSEMBLE 


The above example assumes that the update file FICA UPDTFIX was found 
and applied. 
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Part 3. Learning to Use EXECS 


In previous sections, the CMS EXEC facilities were described in general 
terms to acquaint you with the expressions used in CMS EXEC files and 
the basic way that CMS EXECS function. Also, examples of CMS’ EXEC 
procedures have appeared throughout this publication. You should be 
familiar at least with the material in "Introduction to the EXEC 
Processors" before you attempt to use the information in Part 3. 


"Section 14. Building CMS EXEC Procedures" describes the EXEC 
facilities in detail, with examples of technigues you may find useful as 
you learn about EXEC and develop your own EXEC procedures. 


Special considerations for using CMS commands in EXECS and modifying 
CMS command functions using EXEC procedures are described in "Section 
15. Using CMS EXECS With CMS Commands." 


"Section 16. Refining Your CMS EXEC Procedures" lists several 
techniques you can use to make your EXEC files easier to use and 
provides some hints on debugging EXEC procedures. 


If you are a frequent user of the CMS Editor, then you may be 
interested in "Section 17. Writing Edit Macros," which describes how to 
create your own EDIT subcommands using EXEC procedures. 


Note: If you are using EXEC 2, refer to VWM/SP EXEC 2 Reference, for 
information pertaining to EXEC commands. 
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Section 14. Building CMS EXEC Procedures 


This section discusses various technigues that you can use when you 
write CMS EXEC procedures. The examples are intended only as 
suggestions: you should not feel that they represent either the only way 
or the best way to achieve a particular result. Many combinations and 
variations of control statements are possible; in most cases, there are 
Many ways to do the same thing. 


This section is called "Building CMS EXEC Procedures" because you 
will often find that once you have created an EXEC procedure and begun 
to use it, you continually think of new applications or new uses for it. 
Using the CMS editor, you may guickly build the additions and make the 
necessary changes. You are encouraged to develop EXEC procedures to help 
you in all the phases of your CMS work. 


Note: If you are using EXEC 2, refer to VWM/SP EXEC 2 Reference for 
detailed information. 


What is a Token? 


An executable statement is any line in an EXEC file that is processed by 
the EXEC interpreter, including: 


CMS command lines 

EXEC control statements 
Assignment statements 
Null lines 


Executable statements may appear by themselves on a line oras_ the 
object of another executable statement, for example in an 6&IF or &LOOP 
control statement. If you want to execute CP commands or other EXEC 
procedures in an EXEC, you must use the CP and EXEC commands, 
respectively. CP commands are passed directly to CP for processing. 


All executable statements in an EXEC are scanned by the CMS scan 
routine. This routine converts each word (words are delimited by blanks 
and parentheses) into an eight-character quantity called a token. If a 
word contains more than eight characters, it is truncated on the right. 
If it contains fewer than eight characters, it is padded with blanks. 
When a parenthesis appears on the line, it is treated both as a 
delimiter and as a token. For example, the line: 


ETYPE WHAT IS YOUR PREFERENCE (RED| BLUE) ? 
scans as follows: 
ETYPE WHAT IS YOUR PREFEREN ( RED|BLUE ) ? 


After a line has been scanned, each token is scanned for ampersands 
and substitutions are performed on any variable symbols in the tokens 
before the statement is executed. After elimination of any null 
variables, the statement may contain a maximum of 32 tokens. 


Nonexecutable statements are lines that are not processed by the EXEC 
interpreter, that is, comment lines (those that begin with an *), and 
data lines following an &BEGEMSG, &BEGPUNCH, &BEGSTACK, or 6&BEGTYPE 
control statement. Since these lines are not scanned, words are not 
truncated, and tokens are neither formed nor substituted. 
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Since all executable statements in an EXEC are scanned, and the data 
items are treated as tokens, the term "token" is used throughout this 
section to describe data items before and after scanning. The VM/SP CMS 
Command and Macro Reference, which contains the formats and descriptions 
of the EXEC control statements, uses this convention as well. 
Therefore, aS you create your EXEC procedures, you may think of the 
items that you enter on an EXEC statement as tokens, since that is how 
they are used by the EXEC interpreter. 


Variables 


To make the best use of the CMS EXEC facilities, you should have an 
understanding of how the EXEC interpreter performs substitutions on 
variable symbols contained in tokens. Some examples follow. For each 
example, the input lines are shown as they would appear in an EXEC file 
and as they would appear after being interpreted and executed by EXEC. 
Notes concerning substitution follow each example. 


SIMPLE SUBSTITUTION: Most of the EXEC examples in this publication 
contain variable symbols that result in one-for-one substitution. Most 
of your variables, too, will have a similar relationship. 


Lines After Substitution 
&X = 123 &X = 123 
STYPE &X STYPE 123 


The EXEC interpreter accepts the variable symbol &X and assigns it the 
value 123. In the second statement, &X is substituted with this value, 
and the control statement &TYPE is recognized and executed. 


Lines After Substitution 
&Y = 456 &6Y = 456 
&Z = &Y &Z = 456 


The symbol &Y is assigned a value of 456. In the second statement, the 
symbol &Y is substituted with this value, and this value is assigned to 
&Z. 


SUBSCRIPTS FOR VARIABLES: Since each token is scanned more than once for 
ampersands, you can simulate subscripts by using two variable values in 
the same token. 


Lines After Substitution 
&1 = ALPHA &1 = ALPHA 

&2 = BETA &2 = BETA 

SINDEX1 = 1 SINDEX1 = 1 

&TYPE &EINDEX1 &TYPE ALPHA 
SINDEX1 = 2 SINDEX1 = 2 

STYPE &&INDEX1 STYPE BETA 


In the statement &TYPE S&INDEX1, the token &INDEX1 is scanned the first 
time, and the value &INDEX1 is substituted with the value 1. The token 
now contains &1, which is substituted with the value ALPHA oon a second 
scan. When the value of SINDEX1 is changed to 2, the value of &&INDEX1 
also changes. 


Lines After Substitution 
6I = 2 6I = 2 

&X6I = 5 EX2 = 5 

6I = 1 6I = 1 

&XEI = 2 &X1 = 2 

&X = &XEI + SXEXEL 6X = 2 + 5 
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In the statement &X&I = 5, analysis of the first token results in the 
substitution of the symbol &I with the value of 2. The symbol &X2 is 
assigned a value of 5. 


The value of &I is changed to 1, and the symbol &X1is assigned a 
value of 2. 


In the last statement, &X% = &X&I + &X&XEI, the value of &I in the 
token &X&I is replaced with 1, then the symbol &X1 is substituted with 
its value, which is 2. ,The token &X&X&I is substituted after each of 
three scans: &I is replaced with the value 1, to yield the token &X&X1. 
The symbol &X1 has the value of 2, so the token is reduced to &X2, which 
has a value of 5. 


COMPOUND VARIABLE SYMBOLS: Variable symbols may also be combined with 
character strings. 


Lines After Substitution 
6X = BEE &X = BEE 

STYPE HONEY&X STYPE HONEYBEE 
STYPE ABUMBLEE&X SETYPE ABUMBLE 


In the above example, the first symbol encountered in the scan of 
HONEY&X is &X, which is substituted with the value &BEF. In the second 
STYPE statement, the X is truncated when the line is scanned; the symbol 
& is an undefined symbol and is therefore set to blanks. 


Lines After Substitution 
&X = HONEY &X = HONEY 

&Y = BEE &Y = BEF 

ETYPE &XEY ETYPE 


In the above example, after the symbol &Y is substituted with the value 
BEE, the token contains the symbrol E&XBEE, which is an undefined symbol, 
so the symbol is discarded. 


Lines After Substitution 
&123 = ABCDE 6123 = ABCDE 

&X = 12345678 &X = 12345678 
STYPE ABLE&EX ETYPE AELEABCD 


In this example, the substitution of &X in the token ABLE&&X results in 
the character string ABLE&12345678, which is truncated to eight 
characters, or ABLE&123. The scan continues, and &123 is substituted 
with the appropriate value, to result in ABCDE. The token is again 
truncated to eight characters. 


CONCATENATION OF TOKENS: The &CONCAT built-in function is used to 
concatenate two or more tokens. 


Lines After Substitution 
&X = BB X = BB 
&Y = &CONCAT AA &X CC E&Y = SCONCAT AA BB CC 


STYPE &Y &ETYPE AABBCC 


In the above example, the substitution of &Y results in the character 
string &CONCATAABBCC. The scan continues with the concatenation, the 
result, AABBCC. 


SUBSTITUTING LITERAL VALUES: You might want an ampersand to appear ina 
token. You can use the 6&LITERAL built-in function to suppress’ the 
substitution of variable symbols in a token. 
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Lines After Substitution 


69 = HELLO &9 = HELLO 
SA = GSLITERAL &9 SA = SLITERAL 8&9 
STYPE GA STYPE &9 


Because the value of &A was defined as a literal &9, no substitution is 
performed. 


Lines After Substitution 
STYPE = QUERY STYPE = QUERY ‘ 
6TYPE BLIP QUERY BLIP 


In the above example, even though &TYPE is an EXEC keyword, it is 
assigned the value of QUERY, and substitution is performed when it 
appears on an input line. In this example, when it is substituted with 
its value, the result is a command line which is passed to CMS for 
processing. 


Lines After Substitution 
&CONTROL = FIRST ECONTROL = FIRST 


GSLITERAL &CONTROL ALL & CONTROL ALL 


In this example, &CONTROL iS aSSigned a value as a variable symbol, but 
when it is preceded by the built-in function &1LITERAL, the substitution 
is not performed, so EXEC processes it as a control statement. 


HEXADECIMAL AND DECIMAL CONVERSIONS: You can perform hexadecimal to 


decimal and decimal to hexadecimal conversions in an EXEC if you use the 
control statement &HEX ON. 


Tokens of the form X*'*xxx, can be converted from hexadecimal to 
decimal and from decimal to hexidecinal. The conversion takes place 
according to the rules given below. These rules are in effect only if 
"SHEX ON' is in effect. 


1. Hexadecimnal-to-decimal conversion is performed in the assignment 
statement, and that is the only place where it occurs. 


Example: 
&X = 100 + X*'100 


This results in &X being set to 356 (100 + 256) 


2. Decimal-to-—hexadecinal conversion is performed whenever 
substitution is performed, except on the right-hand-side of an 
assignment. 

Example: 


&STACK LIFO 100 X*100 X'15 
&READ VARS &A &B &C 


This sets &A to 100, &B to 64, and &C to F. 

3. No conversion is performed on the left-hand-side of an assignment 
statement. Instead, the quote in &X%'10 is treated as an illegal 
character in a variable name. 

4. Conversion errors occur if the conversion cannot be perforned, 


either because the result is too large, or because the aumber 
contains invalid digits. 
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Examples: 


&X 
SY 


FFFFFFF 
X"&X 


The result of the conversion of X*FFFFFFF' to decinal 


than the maximum of 99999999 decimal. 


is larger 


Note: No intermediate truncation occurs during conversion, as in 


the preceding example, where X'FFFFFFF contains 9 characters. 
Example: 
STYPE X'FFFF 
The conversion argument is expected to be a decimal number. 
The following illustrates conversions with ‘&HEX ON' in effect: 
EXEC Control Statements 


SCONTROL ALL 
-E1 &HEX ON 


Result After Substitution 


SNUM = X*FFFFFF 
STYPE HEX X*&NOUMM = DEC 6&NUM 


G&NUM = 16777215 
&TYPE HEX FFFFFF 
= DEC 16777215 


-E2 &IF X'16777215 = X"&NUM &GOTO —-E3 SIF 28F5C = FFFFFF 
&GOTO -E3 
STYPE SLITERAL X*'16777215 &TYPE X*'167772 NE X*&NUM 
NE &LITERAL X*&NUM 
&ETYPE X'16777215 NE X*&NUM STYPE 28F5C NE FFFFFF 
-E3 G&NOUM = X'10 &NUM = 16 
&6Y = ENUM + X'"B &Y = 16 + 11 
SETYPE SY XK'8&Y STYPE 27 1B 
-E4 &Y = X'NUM &Y = 22 
&6Z = SCONCAT SLITERAL X'1 X'ENUM &Z = &CONCAT X*'1 22 
&HEX OFF SHEX OFF 
STYPE &Y 6&2 &TYPE 22 X'122 
SHEX ON &HEX ON 
STYPE &Y &2Z STYPE 22 7A 
To suppress hexadecimal conversion during an EXEC procedure after 
having used it, you can use the CMS EXEC control statement: 
GHEX OFF 
so you can use tokens containing the characters X* without the EXEC 


processor converting them to hexadecinal. 


Arguments 


An argument 
symbols 
invoked. For example, 


the tokens 


in an 
&1 through 6&30 that 


links viola ariel oberon 


VIOLA, ARIEL, and OBERON 


is one 
are assigned 
if the EXEC named LINKS is invoked with the line: 


CMS EXEC procedure 


are arguments and are 


of the special variable 
values when the EXEC is 


assigned to 


the variable symbols &1, &2, and &3, respectively. 


You can pass as 
Variable symbols you can 


Many as 30 arguments to an 
set range from &1 to &30Q. 
collectively referred to as the special variable 6&n. 


EXEC procedure; thus the 
These variables are 
Once these symbols 
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are defined, they can be used and tanipulated in the same manner as any 
other variable in an EXEC. They can be tested, displayed, changed, and, 
if they contain numeric quantities, used arithmetically. 


GIF &2 EQ PRINT &GOTO -PR 

STYPE &1 IS AN INVALID ARGUMENT 
61 = 2 

&CT = &1 + 100 


The above examples illustrate some explicit methods of manipulating the 
&n variables. They can also be implicitly defined or redefined by two 
EXEC control statements: &ARGS and &READ ARGS. 


An &SARGS control statement redefines all of the special &n variables. 
The statement: 


GARGS ABC 


assigns the value of A, B, and cC to the variables &1, &2, and 6&3 and 
sets the remaining variables, &4 through &30, to blanks. 


You can also redefine arguments interactively by using the &READ ARGS 
control statement. When EXEC processes this statement, a read request is 
presented to your terminal, and the tokens you enter are assigned to the 
&n variables. For example, the lines: 


STYPE ENTER FILE NAME AND TYPE: 
GS&READ ARGS 
STATE &1 &2 * 


request you to enter two tokens, and then treat these tokens as the 
arguments &1 and &2. The remaining variables &3 through &30 are set to 
blanks. 


If you want to redefine specific &n variables, and leave the values 
of others intact, you can either redefine the individual variables in 
separate assignment statements, or use the variable symbol in the &ARGS 
or &READ ARGS statement. For example, the statement: 


SARGS CONT &2 &3 RETURN &5 6&6 &7 &8 &9 &10 
assigns new values to the variables &1 and &4, but does not change the 


existing values for the remaining symbols through &10. 


If you need to set an argument or &n special variable to blanks, 
either on an EXEC command line or in an &ARGS or &READ ARGS control 
statement, you can use a percent sign (%) in its place. For example, the 
lines: 


GARGS SET QUERY % TYPE 
STYPE &1 62 &3 &4 


result in the display: 
SET QUERY TYPE 


The symbol &3 has a value of blanks, and ag a null token, is discarded 
from the line. 
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USING THE S&INDEX SPECIAL VARIABLE 


The EXEC special variable, SINDEX, initially contains a numeric value 
corresponding to the number of arguments defined when the EXEC was 
invoked. The value of SINDEX is reset whenever an &ARGS or &READ ARGS 
control statement is executed. 


SINDEX can be useful in many circumstances. If you create an EXEC 
that may expect any number of arguments, and you are going to perform 
the same operation for each, you might set a counter and use the value 
of &INDEX to test it. For example, an EXEC named PRINTX accepts 
arguments that are the filenames of ASSEMBLE files: 


&CT = 1 

&LOOP 2 &CT > EINDEX 
PRINT &&CT ASSEMBLE 
&CT = &CT + 1 


In the preceding example, the token &CT is substituted with &1, &2, and 
so on until all of the arguments entered on the PRINTX line are used. 


You can also use SINDEX to test the number of arguments entered. If 
you design an EXEC to expect at least two arguments, the procedure night 
contain the statements: 


SIF SINDEX LT 2 &GOTO -ERR1 


—-ERR1 STYPE INVALID COMMAND LINE 
SEXIT 1 


In this example, if the EXEC is invoked with one or no arguments, an 
error message is displayed and the EXEC terminates processing with a 
return code of 1. 


As another example, suppose you wanted to supply an EXEC with default 
arguments, which might or might not be overridden. If the EXEC is 
invoked with no arguments, the default values are in effect; if it is 
invoked with arguments, the arguments replace the default values: 


&DISP = PRINT 

S&COUNT = 2 

SIF SINDEX GT 2 SEXIT 1 
SIF SINDEX EQ 0 &GOTO -GO 
&COUNT = 6&1 

SIF SINDEX = 2 &DISP = &2 
-GO 


Default values are supplied for the variables &DISP and &COUNT. Then, 
SINDEX is tested, and the variables are reset if any arguments were 
entered. 


CHECKING ARGUMENTS 


There are a number of tests that you can perform on arguments passed to 
a CMS EXEC. In some cases, you may want to test for the length ofa 
specific argument or to test whether an argument is character data or 
Numeric data. To perform these tests, you can use the EXEC built-in 
functions &LENGTH and &DATATYPE. 
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To use either &LENGTH or &DATATYPE, you must first assign a variable 
to receive the result of the function, and then test the variable. For 
example, to test whether an entered argument is five characters long, 
you could use the statements: 


SCLIMIT = GSLENGTH 6&1 
SIF SLIMIT GT 5 SEXIT &LIMIT 


When these statements are executed, if the first argument (&1) is 
greater than five characters, the exit is taken, and the return code 
indicates the length of &1. 


If you wish to check whether a number was entered for an argument, 
use the &DATATYPE function: 


ESTRING = &DATATYPE &2 
SIF &STRING -= NUM &GOTO -ERR4 


In this example, the second argument expected by the EXEC must bea 
humeric quantity. If it is not, a branch is taken to an error exit 
routine. 


Often, you may create an EXEC that tests for specific arguments and 
then takes various paths, depending on the argument. For example: 


SIF &2 = PRINT &GOTO -PR 
SIF &2 = TYPE &GOTO -TY 
SIF &2 = ERASE &GOTO -ER 
GEXIT 


In this EXEC, if the value of &2 is not PRINT, TYPE, or ERASE, or was 
not entered, the EXEC terminates processing. 


&* and &$ 


There are two special EXEC keywords that you may use to test arguments 
passed in an EXEC. They are &* and &$, which can be used only in an &IF 
or an &LOOP control statement. They test the entire range of numeric 
variables &1 through &30, as follows: 


&$: The special token &$ is interpreted as "any of the variables &1, 6&2, 
eee, &30." That is, if the value of any one of the numeric variables 
satisfies the established condition, then the 6&IF statement is 
considered to be true. The statement is false only when none of the 
variables fulfills the specified requirements. 


As an example, suppose you want to make sure that some particular 
value is passed to the EXEC. You can check to see if any of the 
arguments satisfy this condition, as follows: 


&IF &$ EQ PRINT &SKIP 2 
&TYPE PARM LIST MUST INCLUDE PRINT 
SE EXIT 


In this example, the path to the &TYPE statement is taken only when none 
of the arguments passed to the EXEC procedure equal the character string 


PRINT. 
&*: The special token &* is interpreted as "all of the variables 6&1, &2, 


eee, &30." That is, if the value of each of the numeric variables 
satisfies the established condition, then the 6&IF statement is 
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considered to be true. The statement is false when at least one of the 
variables fails to meet the specified requirements. 


Use &* to test for the absence of an argument as follows: 
GIF &* NE ASSEMBLE &EXIT 3 


In this example, if an EXEC is invoked, and none of the arguments equals 
ASSEMBLE, the EXEC terminates with a return code of 3. 


The tokens &* and &$ are set by arguments entered when an EXEC is 
invoked and reset when you issue an &ARGS or &READ ARGS’ control 
statement. If either &* or &$ is null because no arguments are entered, 
the &IF statement is considered a null statement, and no error occurs. 


Execution Paths in a CMS EXEC 


You have already seen examples of the SIF, &GOTO, &SKIP, and 6&LOOP 
control statements. A more detailed discussion on each of these 
statements and additional technigues for controlling execution paths in 
an EXEC procedure follow. 


LABELS IN A CMS EXEC PROCEDURE 


In many instances, an execution control statement in an EXEC procedure 
causes a branch to a particular statement that is identified by a label. 
The rules and conventions for creating syntactically correct EXEC labels 
are: 


e A label must begin with a hyphen (dash) and must have at least one 
additional character following the hyphen. 


e¢ Up to seven additional alphameric characters may follow the hyphen 
(with no intervening blanks). However, the sequence: 


&GOTO —-PROBABLY 


—-PROBABLY 


executes successfully, because when each statement is scanned, the 
token -PROBABLY is truncated to the same eight-character token, 
~PROBABL. 


* A label name may be the object of an &GOTO or &LOOP control 
statement. 


e A label that is branched to must be the first token on a line. It 
may stand by itself, with no other tokens on the line, or it may 
precede an executable CMS command or CMS EXEC control statement. 


The following are examples of the correct use of labels: 


&GOTO -LAB1 

—-LAB1 

-LAB2 SCONTINUE 

-CHECK SIF SINDEX EQ 0 &GOTO -EXIT 
G6IF &INDEX LT 5 &SKIP 

-EXIT SEXIT 4 

STYPE &LITERAL GEINDEX VALUE IS &INDEX 
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CONDITIONAL EXECUTION WITH THE SIF STATEMENT 


The main tool available to you for controlling conditional execution in 
a CMS EXEC procedure is the 6&IF control statement. The 6&IF control 
statement provides the decision-making ability that you need to set up 
conditional branches in your EXEC procedure. 


One approach to decision-making with the &IF control statement is to 
compare two tokens, and perform some action based on the result of the 
comparison. When the comparison is specified true, the executable 
statement is executed. When the comparison is false, control passes to 
the next sequential statement in the EXEC procedure. An example of a 
Simple SIF statement is: 


SIF &1 EQ &2 &STYPE MATCH FOUND 


If the comparand values are not equal, the statement &TYPE MATCH 
FOUND is not executed, and control passes to the next statement in the 
EXEC procedure. If the comparand values are equal, the statement STYPE 
MATCH FOUND is executed before control passes to the next statement. 
SIF statements can also be used to establish a comparison between a 
variable and a constant. For example, if a terminal user could properly 
enter a YES or NO response to a prompting message, you could set up &IF 
statements to check the response as follows: 


SREAD ARGS 

SIF &1 EQ YES &GOTO -YESANS 

SIF &1 EQ NO &GOTO -NOANS 

STYPE &1 IS NOT A VALID RESPONSE (MUST BE YES OR NO) 
SEXIT 

-YESANS 


In this example, the branch to -YESANS is taken if the entered 
argument is YES; otherwise, control passes to the next &IF statement. 
The branch to -NOANS is taken if the argument is NO; otherwise, control 
passes to the &TYPE statement, which displays the entered argument in an 
error message and exits. 


The test performed in an &IF statement need not be a simple test of 
equality between two tokens; other types of comparisons’ can be tested, 
and more than two variables can be involved. The tests that can be 
performed and the symbols you can use to represent them are; 


Symbol Mnemonic Meaning 
= EQ A equals B 
a= NE A does not egual B 
< LT A is less than B 
<= LE A is less than or egual to B (not greater than) 
> GT A is greater than B 
>= GE A is greater than or equal to B (not less than) 
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Compound SIF Statements 
You can place multiple SIF control statements on one line, to testa 
variable for more than one condition. For example, the statement: 

SIF &NOM GT 5 SIF ENUM LT 10 STYPE O.K. 
checks the variable symbol &NUM for a value greater than 5 and less than 
10. If both of these conditions are satisfied, the SIF statement is 


true, and the &TYPE statement isc executed. If either condition is false, 
then the &TYPE statement is not executed. 


The number of 6&IF statements that may be nested is limited only by 
the following criteria: 
CMS EXEC files - a maximum of 32 tokens for variable-length files. 
- 72 characters for fixed-length records. 


EXEC 2 files - the record length of the file. 


BRANCHING WITH THE &GOTO STATEMENT 


The &GOTO control statement allows you to transfer control within your 
EXEC procedure: 
e To a specified EXEC lakel somewhere in the EXEC file: 
&GOTO -TEST 
where -TEST is the label to which control is passed. 
e To a particular line within the EXEC file. For example: 
&GOTO 15 
results in control being passed to statement 15 in the EXEC file. 
e Directly to the top of the EXEC file. For example: 
EGOTO TOP 

passes control to the beginning of the EXEC procedure. 

The &GOTO control statement can be coded wherever an executable 
statement is permitted in an EXEC procedure. One of its common uses is 
in conjunction with the &IF control statement. For example, in the 
statement: 

SIF &SINDEX EQ 0 &GOTC -ERROR 
the branch to the statement labeled -ERROR is taken when the value of 


the &INDEX special variable is zero. Otherwise, control passes to the 
hext sequential statement in the EXEC procedure. 


An &GOTO statement can also stand alone as an EXEC control statement. 
When coded as such, it forces an unconditional branch to the specified 
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location. For example, you might create an EXEC that has’ several 
execution paths, each of which terminates with an &GOTO statement 
leading to a common exit routine: 


-PATH1 SCONTINUE 


&GOTO -EXIT 
-PATH2 SCONTINUE 


&GOTO -EXIT 
&PATH3 &SCONTINUE 


-EXIT &CONTINUE 


You can use the &GOTO control statement to establish a loop. For 
example: 


SGLOBAL1 = &GLOBAL1 + 1 
&ETYPE ENTER NUMBER: 

GREAD VARS &NEXT 

SIF .&NEXT = . &GOTO -FINIS 
SIF &GLOBAL1 = 2 &TOTAL = 0 
ETOTAL = &TOTAL + &NEXT 
&GOTO TOP 

-FINIS 

STYPE TOTAL IS &TOTAL 


In this EXEC example, all of the statements, through the &GOTO fTOP 
statement, are executed repeatedly until a null line is entered in 
response to the prompting message. Then, the branch is taken to the 
label -FINIS and the total is typed. 


Using the &GOTO Control Statement 


When an EXEC procedure processes an 6&GOTO statement, and searches for a 
given label or line number, the scan begins on the line following the 
&GOTO statement, proceeds to the bottom of the file, then wraps around 
to the top of the file and continues to the line immediately preceding 
the &GOTO statement. If there are duplicate labels in an EXEC file, the 
first label encountered during the search is the one that is branched 
to. 


If the label or line number is not found during the scan, EXEC 
terminates processing and displays the message: 


ERROR IN EXEC FILE filename, LINE n —- &SKIP or &GOTO ERROR 


If the label or line number is found, control is passed to that location 
and execution continues. 
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BRANCHING WITH THE &SKIP STATEMENT 


The &SKIP control statement provides you with a second method of passing 
control to various points in an EXEC procedure. Instead of branching to 
a named or numbered location in an EXEC procedure, &SKIP passes control 
a specified number of lines forward or backward in the file. 


You pass control forward in an EXEC by specifying how many lines to 
skip. For example, to handle a conditional exit from an EXEC procedure, 
you could code the following: 


SIF GRETCODE EQ 0 &SKIP 
SEXIT &RETCODE 


where the &EXIT statement is skipped whenever the value of &RETCODE 
equals zero. If the value of E&RETCODE does not equal zero, control 
passes out of the current EXEC procedure with a return code that is the 
nonzero value in &RETCODE. Note that when no &SKIP operand is 
specified, a value of 1 is assumed. 


A succession of &SKIP statements can be used to perform saultiple 
tests on a variable. For example, suppose an argument should contain a 
value from 5 to 10 inclusive: 


SIF &1 LT 5 &SKIP 
GEIF &1 LE 10 &SKIP 
STYPE &1 IS NOT WITHIN RANGE 5-10 


If the value of &1 is less than 5, control passes to the &TYPE control 
statement, which displays the erroneous value and an explanatory 
message. If the value of &1 1s greater than or equal to 5, the next 
statement checks to see if it is less than or equal to 10. If this is 
true, then the value is between 5 and 10 inclusive, and execution 
continues following the &TYPE statenent. 


When you want to pass control toa statement that precedes’ the 
current line, determine how many lines backward you want to go, and code 
&SKIP with the desired negative value: 


&VAL = 1 

ETYPE &VAL 

EVAL = &SVAL + 1 

SIF &VAL NE 10 &SKIP -2 


In this EXEC, the &TYPE statement is executed repeatedly until the value 
of &VAL is 10, and then execution continues with the statement following 
the &IF statement. 


USING COUNTERS FOR LOOP CONTROL 


A primary consideration in designing a portion of an EXEC procedure that 
is to be executed many times is how to control the number of executions. 
One way to control the execution of a sequence of instructions is to 
create a loop that tests and changes the value of a counter. 


Before entering the loop, the counter is initialized to a value. 
Each time through the loop, the counter is adjusted (increased or 
decreased) toward a limit value. When the limit value is reached (the 
counter value is the same as the limit value), control passes out of the 
loop and it is not executed again. For example, the following EXEC 
initializes a counter based on the argument 6&1: 
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SIF &INDEX EQ O SEXIT 12 

STYPE COUNT IS 6&1 

&1= &1- 1 

SIF &1 GT 0 &SKIP -2 

When this EXEC procedure is invoked, it checks that at least one 

argument was passed to it. If an argument is passed, it is assumed to 
be a number that indicates how many times the loop is to execute. Each 
time it passes through the loop, the value of &1 is decreased by 1. 


When the value of 6&1 reaches zero, control passes from the loop to the 
next sequential statement. 


There are several ways of setting, adjusting, and testing counters. 
Some ways to set counters are by: 


e Reading arguments from a terminal, such as: 
SREAD VARS &SCOUNT1 &SCOUNT2 

e Assigning an arbitrary value, such as: 
SCOUNTER = 43 

e Assigning a variable value or expression, such as: 
SCOUNTS = &SINDEX - 1 


Counter values can be increased or decreased by any increment or 
decrement that meets your purposes. For example: 


SCOUNTEM = SCOUNTEM - &SRETCODE 
S&COUNT1 = SCOUNT + 100 


LOOP CONTROL WITH THE &LOCP STATEMENT 


A convenient way to control execution of a sequence of EXEC statements 
is with the &LOOP control statement. An &LOOP statement can be set up 
in four ways: 


e To execute a particular number of statements a specified number of 
times. For example, the statement: 


&LOOP 3 2 


indicates that the three statements following the &LOOP statement are 
to be executed twice. 


e To execute a particular number of statements until a specified 
condition is satisfied. For example: 


&LOOP 4 &X = 0 


The four statements following this statement are executed until the 
value of &X is 0. 


e To execute the statements down to (and including) the statement 
identified by a label for a specified number of times. For example: 


&LOOP -ENDLOOP 6 


The statements between this &LOOP statement and the label -ENDLOOP 
are executed six times. 
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e To execute the statements down to (and including) the statement 
identified by a label until a specified condition is satisfied. In 
the following example: 


&LOOP -ENDLOOP &X = 0 
the statements are executed repeatedly until the value of &X is 0. 


The numbers specified for the number of lines to execute and the 
number of times through the loop must be positive integers. You can use 
a variable symbol to represent the integer. If a label is used to 
define the limit of the loop, it must follow the &LOOP statement (it 
cannot precede the &LOOP statement). 


In a conditional &LOOP statement, any variable symbols in the 
conditional phrase are substituted each time the loop is executed. For 
example, the statements; 


&X = 0 

&LOOP -END &X EQ 2 
&X = &X + 1 

-END &TYPE &X 


are interpreted and executed as follows: 
1. The variable &X is assigned a value of 0. 


2. The &LOOP statement is interpreted as a conditional form; that is, 
to loop to -END until the value of &X equals 2. Since the value of 
&X is not 2, the loop is entered. 


3. The variable &X is increased by 1 and is then displayed. 


4. Control returns to the beginning of the loop, where &X is tested to 
see if it equals 2. Since it does not, the loop is executed again 
and 2 is displayed. The next time through the loop, when &X equals 
2, control is passed to the EXEC statement immediately following 
the label -END. 


When this EXEC procedure is executed, the following lines are 
displayed: 


1 
2 


at which time the value of &X equals 2; the loop is not executed again. 
Another example of a conditional loop is: 
&Y = ELITERAL A&B 
ELOOP 2 .&X EQ SLITERAL .& 
&X = &SUBSTR &Y 2 1 
ETYPE &X 
These statements are interpreted and executed as follows: 


1. The variable &Y is set to the literal value A&B. 


2. The two statements following the &LOOP statement are to be executed 
until the value of &X is &. 


3. The &SUBSTR built-in function is used to set the variable &X to the 
value of the second character in the variable 6&Y, which is a 
literal ampersand (&). 
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4. The ampersand is typed once, and the loop does not execute again 
because the condition that the value of &X be a literal ampersand 
is net. 


NESTING CMS EXEC PROCEDURES 


If you want to use a CMS EXEC procedure within another CMS EXEC, you 
must use the EXEC command to execute it. For example, if you have the 
statement: 


EXEC TEST 


in an EXEC procedure, it invokes the EXEC procedure TEST. The procedure 
TEST EXEC executes independently of the other EXEC; the variables &1, &2 
and so on are assigned values and the default settings for control 
statements such as S&CONTROL and &HEX are _ reset. When TEST EXEC 
completes execution, control returns to the next line in the calling 
EXEC, where the values for variable symbols and EXEC settings are the 
same as when the TEST EXEC was invoked. 


Passing Arguments to Nested Procedures 


Variables in an EXEC file have meaning only within the particular 
procedure in which they are defined. There are two methods you can use 
to pass variable information to nested EXECS. One way is to pass 
arguments on the EXEC command line. For example, if the CHECK EXEC 
contains the line: 


EXEC COUNTEM &ITEMCT &NUM 


then the current values of S&ITEMCT and &NUM are assigned to the variable 
symbols &1 and 6&2 in COUNTEM EXEC. (The values of &1 and 6&2 in CHECK 
EXEC do not change.) 


You can also use the ten special variables &GLOBALO through &GLOBAL9S. 
These variables can only contain integral numeric values; you cannot 
assign them character-string values. These variables can be used to set 
up arguments to pass’ to nested procedures, or to communicate between 
EXEC files at different recursion levels. 


Thus, if CHECK EXEC contains: 


&GLOBAL1 = 100 
EXEC COUNTEM 


The variable &GLOBAL1 has a value of 100 in COUNTEM EXEC, which may also 
test and modify it. 


Horizontal communication by means of global variables is also 
possible at recursion levels 2 and above. For example: EXEC A calls 
EXEC B, which sets &GLOBAL1 to 2 and exits, then EXEC A (STILL ACTIVE) 
calls EXEC C, which finds that &GLOBAL1 has a value of 2, as set by EXEC 
B. 


The CMS EXEC interpreter can handle up to 19 levels of recursion at 


one time, that is, up to 19 EXECS may be active, one nested within 
another. An EXEC may also call itself. 
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You can test the 6GLOBAL special variable to see if an EXEC is 
executing within another procedure and if so, at what level of recursion 
it is executing. For example, if the file RECOMP EXEC contained the 
lines: 


SIF &GLOBAL EQ 2 &GOTO -2NDPASS 


EXEC RECOMP 


-2NDPASS &TYPE SECOND PASS BEGINS 


then when the line “EXEC RECOMP" is executed, control passes’ to the 
beginning of the EXEC; the value of &GLOBAL changes from 1 to 2; and 
control is passed to the &TYPE statement at the label 2NDPASS. 


EXITING FROM CMS EXEC PROCEDURES 


Execution in a CMS EXEC procedure proceeds sequentially through a file, 
line by line. When a statement causes control to be passed to another 
statement, execution continues at the second statement, and again 
proceeds sequentially through the file. When the end of the file is 
reached, the EXEC terminates processing. Frequently, however, you may 
not want processing to continue to the end of the file. You can use the 
SEXIT statement to cause an immediate exit from EXEC processing anda 
return to the CMS environment. If the EXEC has been invoked from 
another EXEC, control is returned to the calling EXEC file. FOr 
example, the statenent: 


G6IF SRETCODE -= 0 &EXIT 


would cause an immediate exit from the EXEC if the return code from the 
last issued CMS command was not zero. 


You can use the &SEXIT statement to terminate each of a_ series of 
execution paths in an EXEC. For example, uSing the following 
statements, 


SIF &1 EQ PRINT &GOTO -PRINT 
SIF &1 EQ TYPE &GOTO -TYPE 
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you ensure that once the path through the -PRINT routine has been taken, 
the EXEC does not continue processing with the -TYPE routine. 


The &EXIT control statement also provides a special function that allows 
you to pass a_ return code to CMS or to the program or EXEC that called 
this EXEC. You specify the return code value on the &SEXIT control 
statement as follows: 


GEXIT 4 
Execution of this line results in a return to CMS with a ready message: 
R(000084) ; 
If you have a variety of exits in an EXEC, you can use a different value 
following each &EXIT statement, to indicate which path had been taken in 


the EXEC. 


You can also use a variable symbol as the value to. be passed as the 
return code: 


SEXIT &VAL 


Another common use of the &EXIT statement is to cause an exit to be 
taken following an error in a CMS command, and using the return code 
from the CMS command in the &SEXIT statement: 


SIF GSRETCODE NE O &EXIT &SRETCODE 


Terminal Communications 


You can design EXECS to be used interactively, so that their execution 
depends on information entered directly from the terminal during the 
execution. With the &TYPE statement, you can display a line at the 
terminal, and with the §READ statenent, you can read one or more lines 
from the terminal or console stack. Used together, these statements can 
provide a prompting function in an EXEC: 
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STYPE WHAT DO YOU WANT TO DO NOW? 
&TYPE ENTER (STOP CONTINUE REPEAT): 
GREAD VARS &LABEL 

&GOTO —-&LABEL 


-CONTINUE 


—-REPEAT 


In this example, the &READ control statement is used with the VARS 
operand, which accepts the words entered at the terminal as values to be 
assigned to variable symbols. If the word STOP is entered in response to 
the &READ VARS statement in this example, the variable symbol &LABEL is 
assigned the value STOP. Then, in the &GOTO statement, the symbol is 
substituted with the value STOP, so the branch is taken to the label 
-STOP. 


You can specify up to 17 variable names on an &READ VARS control 
statement. If you enter fewer words than are expected, the remaining 
variables are set to blanks. If you enter a null line, any variable 
symbols on the &READ line are set to blanks. If the execution of your 
EXEC depends on a value entered as a result of an &READ VARS, you might 
want to include a test for a null line immediately following the 
statement; for example: 


GREAD VARS &TITLE &SUBJ 
SIF .&TITLE = . &EXIT 100 


If no tokens are entered in response to the terminal read request, the 
variable &TITLE is null, andthe EXEC terminates with a return code of 
100. 


If you are writing an EXEC that may receive a number of tokens fron 
the terminal, you may find it more convenient to use the &READ ARGS form 
of the &READ control statement. When the &READ ARGS statement reads a 
line from the terminal, the tokens entered are assigned to the 6&n 
special variables (&1, &2, and so on). 


READING CMS COMMANDS AND CMSEXEC CONTROL STATEMENTS FROM THE TERMINAL 


, 
When you use the &READ control statement with no operands, or with a 
humeric value, EXEC reads one line or the specified number of lines fron 
the terminal. These lines are treated, by EXEC, as if they were in the 
EXEC file all along. For example, if you have an EXEC named COMMAND that 
looks like the following: 


&ETYPE ENTER NEXT COMMAND: 
&READ 1 
&SKIP -2 


all the commands you enter during the terminal session are processed by 
the EXEC. Each time the &READ statement is executed, you enter a CMS 
command. When the command finishes, control returns to EXEC, which 
prompts you to enter the next command. Since the CMS commands are all 
being executed from within the EXEC, you do not receive the CMS ready 
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message at the completion of each command. 


You could also enter EXEC control statements Or assignment 
statements. To terminate the EXEC and return to the CMS environment, 
you must enter the EXEC control statement &EXIT from the terminal: 


Gexit 


DISPLAYING DATA AT A TERMINAL 


You can use the &TYPE and &BEGTYPE control statements to display lines 
from your EXEC at the terminal. In addition, you can use the CMS TYPE 
command to display the contents of CMS files. 


When you use the &TYPE control statement, you can display variable 
symbols as well as data. Variable symbols on an &TYPE control statement 
are substituted before they are displayed. For example, the lines: 


SNAME = ARCHER 
ETYPE &NAME 


result in the display: 
ARCHER 


You can use the &TYPE statement to display prompting messages, error 
or information messages, or lines of data. 


In an EXEC file with fixed-length records, only the first 72 
characters of each line are processed by the EXEC interpreter. 
Therefore, if you want to use the &TYPE control statement to display a 
line longer than 72 characters, you must convert the file into 
variable-length records. 


All of the words in an &TYPE control statement are scanned into 
8-character tokens. If you need to display a word that has more than 8 
characters, you must use the &BEGTYPE control statement. The &BEGTYPE 
control statement precedes one or more data lines that you want to 
display; for example: 


&BEGTYPE 

THIS EXEC PERFORMS THE FOLLOWING FUNCTIONS: 

1. IT ACCESSES DISKS 193, 194, and 195 AS 
B, C, AND D EXTENSIONS OF THE A-DISK. 

2. IT DEFINES, FORMATS, AND ACCESSES A 
TEMPORARY 195 DISK (E). 

& END 


The SEND statement must be used to terminate a series of lines 
introduced with the &BEGTYPE statement. "&END" must begin in column 1 of 
the EXEC file. 


The lines following an &BEGTYPE statement, up to the &END statement, 
are not scanned by the EXEC interpreter. Therefore, no substitution is 
performed on the variable symbols on these data lines. If you need to 
display a symbol, you must use the &TYPE control statement. To display a 
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combination of scanned and unscanned lines, you might need to use both 
the &TYPE and &BEGTYPE control statements: 


&BEGTYPE 

EVALUATION BEGINS... 
& END 

STYPE &VAL1 IS &NUM1. 
STYPE &VAL2 IS &NUM2. 
&BEGTYPE 

EVALUATION COMPLETE. 
SEND 


If you use the &BEGTYPE control statement in an EXEC file with 
fixed-length records, and you want to display lines longer than 72 
characters, you must use the ALL operand. For example: 


&SBEGTYPE ALL 

e«--data line of 103 characters 
«--data line of 98 characters 

---data line of 50 characters 

& END 


You can display lines of up to 130 characters in this way. When you 
enter lines that are longer than the record length in an EXEC file, the 
records are truncated by the editor. You must increase the record length 
of the file by using the LRECL option of the EDIT command, for example: 


edit old exec a (lrecl 130 


Using the CMS TYPE Comman 


You can use the TYPE command in an EXEC file to display data files, or 
portions of data files. For example, you might have a number of files 
with the same filetype; the files contain various kinds of data. You 
could create an EXEC that invokes the TYPE command to display a 
particular file as follows: 


GIF GINDEX EQ 2 SIF 6&2 EQ ? &GOTO -TYPE 


-TYPE 
ACCESS 198 B 
TYPE &1 MEMO B 


The filetype MEMO is a reserved filetype, which accepts data in 
uppercase and lowercase; you can use it for documentation files or 
programming notes. 


Controlling Terminal Displays 


The two CMS Immediate commands that control terminal display are HT 
(halt typing) and RT (resume typing). When data is being displayed at 
your terminal, you can suppress the display by signaling an attention 
interruption and entering: 


ht 
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This command affects output that is being displayed: 


e AS a response to a CMS command, including prompting messages, error 
messages, Or normal display responses (as from the TYPE command) 


e From a progran 
e In response to an &TYPE or &BEGTYPE request in an EXEC 


Once display has been suppressed, and before the command, program, or 
EXEC completes execution, you can request that display be resumed by 
signaling another interruption and entering: 


rt 


In an EXEC file, if you want to halt or resume display, you must use 
the &STACK control statement to enter the RT or HT commands or use the 
CMS commands SET CMSTYPE RT and SET CMSTYPE HT. For example, the ACCESS 
command issues a message when a disk is accessed: 


D(198) R/O 


If you are going to issue the ACCESS command within a CMS EXEC and you 
do not wish this message displayed, you could enter the lines: 


SET CMSTYPE HAT 
ACCESS 198 D 


ESTACK HT 
ACCESS 198 D 


When you halt CMS terminal display with an HT command, all displaying, 
except for CMS Error messages with a suffix letter of S ort, is 
suppressed for the remainder of the EXEC file's execution. To reverse 
the suppressed display, use the RT immediate command or the SET CMSTYPE 
RT. To execute the RT Immediate command in an EXEC, use either of the 
statements: 


ESTACK RT 
SET CMSTYPE RT 


The STYPEFLAG Special Variable: You can test the current value of the 
display controlling an EXEC with the &TYPEFLAG special variable. The 
value of &TYPEFLAG can only be one of the literal values HT or RT. For 
example: 


SIF &$ EQ NOTYPE &STACK HT 


SIF &TYPEFLAG EQ HT &SKIP 3 
&TYPE LINE 

ETYPE LINE2 

STYPE LINE3 

& CONTINUE 


In this example, if NOTYPE is entered as an argument when the EXEC is 
invoked, the CMS command SET CMSTYPE HT is executed, hence no display 
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appears at the terminal. Within the EXEC, the variable &TYPEFLAG is 
tested, and, if it is HT, then a series of &TYPE statements is skipped. 
Since EXEC does not have to process these lines, you can save time and 
system resources by not processing then. 


Reading from the Console Stack 


When you are in the CMS environment executing programs or CMS commands, 
you can stack commands, either by entering multiple command lines 
separated by the logical line end symbol, as follows: 


print myfile listing#écp query printer 


or by Signaling an attention interruption and entering a command line, 
as follows: 


print myfile listing 
q 
cp query printer 


In both of the preceding examples, the second command line is saved 
in the console stack. Whenever a read occurs in your virtual machine, 
CMS reads lines from the console stack, if there are any lines in it. 
If there are no lines in the stack, the read results in a physical read 
to your terminal (on a typewriter terminal, the keyboard unlocks). 


A virtual machine read occurs whenever a command or subcommand 
finishes execution, or when an EXEC or a program issues a read request. 
Many CMS commands also issue read requests, for example, SORT and 
COPYFILE. If you want to execute one of these commands in an EXEC, you 
may want to stack, in the console stack, the response to the read 
request so that when it is issued it is immediately satisfied. For 
example: 


GSTACK 42-121 1 
COPYFILE &NAME LISTING A = ASSEMBLE = (SPECS 


When the COPYFILE command is issued with the SPECS option, a prompting 
message for a specification list is issued, followed by a read request. 
In this EXEC, the request is satisfied with the line stacked with the 
G&STACK control statement. If the response were not stacked, you would 
have to enter the appropriate information from the terminal during the 
execution of the EXEC that contained this COPYFILE command line. 


In addition to stacking predefined responses to commands and 
programs, you can use the console stack to stack CMS commands and EDIT 
subcommands, as well as data lines to be read within the EXEC. 


The number of lines that you can place in the console stack at any 
one time varies according to the amount of storage available in your 
virtual machine for stacking. You may want to stack one or two lines at 
a time, or you may wish to stack many lines. There are several features 
available in EXEC that can help you manipulate the stack. 
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Exchanging Data Between Programs through the Stack 


The Console Stack is composed of the terminal input buffer and the 
program stack. Lines typed at the terminal (maximum length of 130 
characters per line) are placed in the terminal input buffer. Lines 
transmitted by programs through the CMS ATTN function are placed in the 
program stack (maximum length of 255 characters per line). 


When the WAITRD function is called (as a result of a RDTERM macro 
call, for example), it will look in the most recently created buffer of 
the program stack (see BUFFER #2 in Figure 28). As each buffer is 
exhausted, RDTERM will look to the next buffer in the program stack 
(BUFFER #1). If the program stack is empty, WAITRD will then look in 
the terminal input buffer for an input line. If the terminal input 
buffer is also empty, then a "console read I/O" will be issued to 
acquire data from the terninal. 


Previously stacked lines read from the program stack will not have 
changed since the time they were stored by ATIN (unless uppercase 
translation has been requested). Before lines are extracted from the 
terminal input buffer, they are scanned by CP (when typed) for 
characters defined by the CP TERMINAL command (or for their default 
values). WAITRD will then scan them for X'15' (logical end of line 
Character), X*'00' (physical end of line character), and for any other 
character defined through a CMS "SET INPUT’ command. 


The MAKEBUF, DROPBUF, SENTRIES, and DESBUF CMS commands allow you to 
create buffers in the frogram stack, eliminate some or all of the 
program stack buffers, determine the number of lines in the program 
Stack, and empty both the program stack and the terminal input buffer. 
These commands may also be called from a terminal (as CMS commands), 
from EXEC files, or from assembler language programs. A complete 
description of these commands can be found in the publication VM/SP CHS 
Command and Macro Reference. 


| Note: Lines read from the terminal or stacked in the terminal input 


buffer can be restacked in the program stack, using the ATTN function, 
and executed ata later time. The line length specified in the 
parameter list for the ATTN function should be the same length as the 
line that was previously read from the terminal or the terminal input 
buffer. A line stacked again by ATTN, using a line length greater than 
the line length read from the terminal or the console input buffer, may 
result in an error when execution of the stacked line is attempted. 


&SBEGSTACK and §SBEGSTACK ALL 


AY EY CLE ETI <= SD TSA EAT! 


Just as the &TYPE control statement has an &BEGTYPE counterpart, the 
ESTACK control statement has an &REGSTACK counterpart. You can stack 
multiple data lines following an &BEGSTACK statement. Lines stacked in 
this way are not scanned by the EXEC processor, and no substitution is 
performed on variable symbols. For example, the lines: 


&BEGSTACK 
eeeline of data 
e--e-line of data 
-e--line of data 
SEND 


stack three data lines in the stack. The stacked lines must be followed 


by an &END control statement, which must be entered in the EXEC file 
beginning in column 1. 
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RDTERM 
ATTN 
ATTN MACRO 


BUFFER #2 


BUFFER #1 


BUFFER #0 


PROGRAM STACK 


TERMINAL INPUT BUFFER 


Figure 28. The Console Stack 


If you have an EXEC with fixed-length records, and you want to stack 
data lines longer than 72 characters, you must use the ALL operand of 
the &BEGSTACK control statement: 


&BEGSTACK ALL 

eeeline of 103 characters 
~e-eline of 98 characters 

eeeline of 60 characters 

& END 


The ALL operand is not necessary for variable-length EXEC files. 
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Stacking FIFO and LIFO 


When you are stacking multiple lines in an EXEC, you may choose to 
reverse the sequence in which lines are read in from the stack. The 
default seguence is FIFO (first-in, first-out), but you may specify LIFO 
(last-in, first-out) when you enter the &STACK or &BEGSTACK control 
statement. For example, execution of the lines: 


SSTACK &TYPE A 
SSTACK &TYPE B 
S&STACK LIFO &TYPE C 
SSTACK LIFO &TYPE D 
&S&STACK &TYPE E 


results in the display: 


Hore OO 


The EXEC special variable &REALFLAG always contains one of two values, 
STACK or CONSOLE. When it contains the value STACK, it indicates that 
there are lines in the stack. When it contains the value CONSOLE, it 
indicates that the stack is empty and that the next read request results 
in a physical read to the terminal (console). 


You can test this value in an EXEC, for example: 


SIF GSREADFLAG EQ STACK &SKIP 2 
STYPE STACK EMPTY 

SEXIT 

&SCONTINUE 


You might use a Similar test in an EXEC that processes a number of lines 


from the stack, and loops through a series of steps until the stack is 
empty. 


STACKING CMS COMMANDS 


Whenever you place a command in the conscle stack, it remains there 
until a read request is presented to the terminal. If the request is the 
result of an &READ control statement, then the line is read from the 
stack. For example, the lines: 


&STACK CP QUERY TIME 
S&S READ 


result in the command line being stacked, read in, and then executed. 


If there are no read requests in an EXEC file, then any commands that 
are stacked are executed after the EXEC has finished and has returned 
control to the CMS environment. For example, consider the lines: 


TYPE &1 LISTING A 
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ACCESS 198 A 
TYPE &1 LISTING A 


If this EXEC is located on your 191 A-disk, then when the ACCESS command 
accesses a new A-disk, CMS cannot continue reading the EXEC file and 
issues an error message. However, if the EXEC was written as follows: 


TYPE &1 LISTING A 
&ESTACK ACCESS 198 A 
&STACK TYPE &1 LISTING A 


then, after the TYPE command, the next command lines are stacked, the 
EXEC finishes executing and returns control to CMS, which reads the next 
command lines from the console stack. 


When you stack either CMS commands or data with the §&STACK control 
statement in an EXEC procedure, the EXEC processor treats everything 
except the immediate commands, HT and RT, as data. Control characters 
such as the character delete and line end character are not recognized 
and therefore not interpreted as performing any special function. The 
logical control characters as defined in the CP TERMINAL command, are 
not substituted with their special values, since the EXEC lines are 
being read from disk and not from a terminal. 


Stacking EDIT Subcommands 


If you want to issue the EDIT command from within an EXEC, you might 
want to stack EDIT subcommands to be read by the CMS editor. You should 
stack these subcommands, either with &STACK statements, or with the 
&EBEGSTACK statement, just before issuing the EDIT command. For example: 


&BEGSTACK 

CASE 

GET SETUP FILE A 1 20 
TOP 

LOCATE /XX/ 

SEND 

&STACK REPLACE 

EDIT &1 DATA (LRECL 120 


If this EXEC is named EDEX, and you invoke it with: 
edex fr01 


the EDIT subcommands are stacked in the order they appear in the EXEC. 
The EDIT command is invoked to edit the file FRO1 DATA, and the EDIT 
subcommands are read from the stack and executed. When the stack is 
empty, your virtual machine is in the edit environment in input mode, 
and the first line you enter replaces the existing line that contains 
the character string XX. 


Note that all of the EDIT subcommands in the example, except for the 
REPLACE subcommand, are stacked within an &BEGSTACK stack, and that the 
REPLACE subcommand 1s stacked with &STACK. If you are creating EXEC 
files with fixed-length records, you must use &STACK to stack the INPUT 
and REPLACE subcommands. If you use &BEGSTACK, then the INPUT and 
REPLACE subcommands are treated as if they contain text data, and so 
insert or replace one line in the file (a line of blanks). This is not 
true, however, for variable-length FXEC files. 


Similarly, if you want to stack a null line, to change from input 
mode to edit mode in an EXEC, you must use the &STACK statement with no 
other data on the line (in both fixed- and variable-length EXEC files), 
for example: 
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&STACK INPUT 
&BEGSTACK 

---data line 
---data line 
---data line 


& END 

GESTACK 
S&STACK FILE 
EDIT &1 &2 
SEXIT 


When this EXEC is invoked with a filename and filetype as arguments, the 
INPUT subcommand, data lines, null line, and FILE subcommand are placed 
in the stack before the EDIT ccmmand is issued. The data lines are 
placed in the specified file and the file is written onto disk before 
the EXEC returns control to CMS. 


STACKING LINES FOR EXEC TO READ 


Lines in the console stack can be read by the EXEC interpreter with an 
GSREAD control statement; for example: 


-SETUP 
&LOOP 3 ENUM = 50 
&STACK &NUM &CHAR 
ENUM = ENUM + 1 
SCHAR = &CONCAT &STRNG &NUM 


~READ 
SLOOP -FINIS &REALTFLAG EQ CONSOLE 
&READ ARGS 
-~FINIS 


In this EXEC procedure, the statements following the label -SETUP stack 
a number of lines. The variables &NUM and &CHAR are substituted before 
they are stacked. At the label -READ, the lines are read in from the 
stack and processed. The values stacked are read inas_ the variable 
symbols &1 and &2. Control passes out of the loop when the’ stack is 
empty. 


CLEARING THE CONSOLF STACK 


If you use the console stack in an EXEC procedure, you should be sure 
that it is empty before you begin stacking lines in it. Also, you 
should be sure that it is empty before exiting from the EXEC (unless you 
have purposely stacked CMS commands for execution). 


One way to clear a line from the stack without affecting the 
execution of your EXEC is to use the &READ VARS or &READ ARGS control 
statement. You can use &READ VARS without specifying any variable 
symbols so that the line read is read in and effectively ignored. For 
example: 


&LOOP 1 &S&READFLAG EQ CONSOLE 
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GREAD ARGS 


If these lines occur at the beginning of an EXEC file, they ensure that 
any stacked lines are cleared. If the EXEC is named EXEC? and is 
invoked with the line: 


execl#type.help memo#type print memo 


then the lines TYPE HELP MEMO and TYPE PRINT MEMO are cleared from the 
stack and are not executed. 


You could use the same technique to clear the stack incase of an 
error encountered in your EXEC, so that the stack is cleared before 
returning to CMS. You would eSpecially want to do this if you stacked 
data lines or EXEC control statements that have no meaning to CMS. 


Another way to clear the console stack is with the CMS’ function 
DESBUF. For example: 


&IF &READFLAG EQ STACK DESBUF 


When you use the DESBUF function to clear the console input stack, the 
output stack is also cleared. The output stack contains lines that are 
waiting to be displayed or typed at the terminal. Frequently, when an 
EXEC iS processing, output lines are stacked, and are not displayed 
immediately following the execution of an &TYPE statement. If you want 
to display all pending output lines before clearing the console input 
stack, you should use the CONWAIT function, as follows: 


CONWAIT 
SIF &READFLAG EQ STACK LCESBUF 


The CONWAIT function causes a suspension of program execution until the 
console output stack is empty. If there are no lines waiting to be 
displayed, CONWAIT has no effect. 


Clearing the stack is important when you write edit macros, since all 
subcommands issued in an edit macro must be first stacked. See "Section 
17. Writing Edit Macros" for additional information on using the console 
stack. 


File Manipulation with CMS EXECs 


You can, to a limited degree, read and write CMS disk files using EXECs. 
You can stack files with a filetype of EXEC in the console’ stack and 
then read them, one record at a time, with &READ control statements. All 
data items are truncated to eight characters. You can write a file, one 
record at a time, with the &PUNCH control statement, and then you can 
read the spool punch file onto disk. Examples of these technigues 
follow. 


STACKING EXEC FILES 


There are two methods to stack EXEC files in the console stack. One is 
illustrated using aCMS EXEC file, as shown in the following PREFIX 
EXEC: 


Section 14. Building CMS EXEC Procedures 323 


ELNAME = &SCONCAT &1 * 

LISTFILE S&LNAME SCRIPT * (EXEC 
EXEC CMS &STACK 

&LOOP -END &READFLAG EQ CONSOLE 
SREAD VARS &NAME &TYPE &MOD 
SSUFFIX = &SSUBSTR &NAMNE 3 6 
GNEWNAM = &SCONCAT &2 &SUFFIX 
RENAME SNAME &TYPE &MOD SNEWNAM S&TYPE &SOD 
SIF SRETCODE EQ O &SKIP 

STYPE FILE SNAME &TYPE NOT RENAMED 
-END 


This EXEC procedure is invoked with two arguments, each two characters 
in length, which indicate old and new prefixes for filenames. The EXEC 
renames files with a filetype of SCRIPT that have the first prefix, 
changing only the prefix in the filenane. 


The LISTFILE command, invoked with the EXEC option, creates a CMS 
EXEC file in the format: 


&1&2 filename SCRIPT mode 
When the EXEC is invoked with the line: 


EXEC CMS &STACK the argument &STACK is substituted for the variable 
symbol &1 in each line in the CMS EXEC. The execution of the CMS EXEC 
effectively stacks, in the console stack, the complete file 
identifications of the files listed: 


&STACK filename SCRIPT mode 
E&ESTACK filename SCRIPT mode 


These stacked lines are read back into the EXEC, one at a time, and the 
tokens "filename", "SCRIPT", and "mode" are substituted for the variable 
symbols &NAME, &TYPE, and &MOD. 


Using the &SUBSTR and &SCONCAT built-in functions, the new name for 
each file is constructed, and the RENAME command is issued to rename the 
files. 


For example, if you invoke the EXEC procedure with the line: 
prefix ab xy 


all SCRIPT files that have filenames beginning with the characters AB 
are renamed so that the first two characters of the filename are XY. A 
sample execution summary of this EXEC is illustrated under "Debugging 
EXEC Procedures" in "Section 16. Refining Your EXEC Procedures." 


Stacking Data Files 


You can create a data file, containing fixed-length records, using a 
filetype of EXEC. To stack these data lines in the console stack, you 
can enter them following an &BEGSTACK (or S&BEGSTACK ALL) control 
statement. For example, the file DATA EXEC is as follows: 


&BEGSTACK 


HARRY 10/12/48 
PATTI 1/18/49 
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DAVID 5/20/70 
KATHY 8/6/43 
MARVIN 2/28/50 


The file BDAY EXEC contains: 


SCONTROL ERROR 

EXEC DATA 

SIF EREADFLAG EQ CONSOLE &GOTO -NO 
GSREAD VARS &NAME EDATE 

SIF &NAME NE &1 &SKIP -2 
—-FOUND 

EIF .&1 EQ . SEXIT 

STYPE &1 'S BIRTHDAY I5 &DATE 
CONWAIT 

DESBUF 

SEXIT 

-NO &TYPE &1 NOT IN LIST 
GSEXIT 


When the BDAY EXEC is invoked, it expects an argument that isa first 
Mame. The function of the EXEC is to display the birthday of the 
specified person. A sample execution of this EXEC might be: 


bday kathy 
KATHY *S BIRTHDAY IS 8/6/43 
R; 


BDAY EXEC first executes the DATA EXEC, which stacks names and dates 
in the console stack. Then, BDAY EXEC reads one line at a time from the 
stack, assigning the variable names &NAME and &DATE to the’ tokens on 
each line. It compares &SNAME with the argument read as &1. When it finds 
a match, it displays the message indicating the date, and clears the 
console stack after waiting for terminal output to finish. 


Note that the file DATA EXEC begins with an &BEGSTACK control 
Statement, but contains no &END statement. The stack is terminated by 
the end of the EXEC file. "Writing Data Files" describes a technigue 
you might use to add new names and birth dates to the DATA EXEC file. 


Writing Data Files 


You can build a CMS file in your virtual card punch using the &PUNCH and 
SBEGPUNCH control statements. Depending on the spooling characteristics 
of your virtual punch, the file that you build may be sent to another 
user's card reader, or to your own virtual card reader. When you read 
the file with the CMS READCARD command, the spool reader file becomes a 
CMS disk file. 


The following example illustrates how you might use your card punch 
and reader to update a CMS file by adding records to the end of it. The 
file being updated is the DATA EXEC, which is the input file for the 
BDAY EXEC, shown in the example in "Stacking Data Files." You could 
create a separate CMS EXEC to perform the update, but this example shows 
how you might modify the BDAY EXEC to perform the addition function 
(ellipses indicate the body of the EXEC, which is unchanged): 
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&CONTROL ERROR 
GIF &1 EQ ADD EGOTO —-ADDNAME 


SEXIT 

-ADDNAME 

STYPE ENTER FIRST NAME AND DATE IN FORM MM/DD/YY 
&READ VARS &NAME SDATE 

SIF .GNAME = . &SKIP 3 

&PUNCH SNAME &DATE 

ETYPE ENTER NEXT NAME OR NULL LINE: 
&SKIP -4 

CP SPOOL PUNCH TO * 

CP CLOSE PUNCH 

READCARD NEW NAMES 

COPYFILE NEW NAMES A DATA EXEC A (APPEND 
SIF &RETCODE = 0 &SKIP 2 

ETYPE ERROR CREATING FILE 

GEXIT &RETCODE 

ERASE NEW NAMES 


When BDAY EXEC is invoked with the keyword ADD, you are prompted to 
enter lines to be added to the data file. Each line that you enter is 
punched to the card punch. When you enter a null line, indicating that 
you have finished entering lines, the CP commands SPOOL and CLOSE direct 
the spool file to your card reader and close the punch. 


The file is read in as the file NEW NAMES, which is appended to the 
file DATA EXEC using the COPYFILE command with the APPEND option. The 
file NEW NAMES is erased and the EXEC terminates processing. 


When you punch lines in your virtual punch, the lines are not released 
as a CP spool file until the punch is closed. Since the EXEC processor 
does not close the virtual punch when it terminates processing, you must 
issue the CLOSE command to release the file. You can do this in the EXEC 
with the command line: 


CP CLOSE PUNCH 


or from the CMS environment after the EXEC has finished. If you use the 
CLOSE command in the EXEC, you must preface it with CP. 


The CMS PUNCH command, which you can use ina CMS EXEC to punch an 
entire CMS file, closes the punch after punching a file. Therefore, if 
you want to create a punch file using a combination of &PUNCH control 
statements and PUNCH commands, you must spool your punch using the CONT 
option, so that a close request does not affect the file: 


CP SPOOL PUNCH TO * CONT 
&PUNCH FIRST FILE 

& PUNCH 

PUNCH FPILE1 TEST ( NOHEADER 
&PUNCH SECOND FILE 

&PUNCH 

PUNCH FILE2 TEST ( NOHEADER 
CP SPOOL PUNCH CLOSE NOCONT 


The preceding example punches title lines introducing the files punched 
with the CMS PUNCH command. The null &PUNCH statements punch blank 
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lines. The PUNCH command is issued with the NOHEADER option, so that a 
read control card is not punched. 


You can also use an EXEC procedure to punch a job to send to the CMS 
batch facility for processing. The batch facility, and an example of 
uSing an EXEC to punch a job to it, are described in "Section 12. Using 
the CMS Batch Facility." 


Using &PUNCH and &BEGPUNCH 


All lines’ punched to the virtual card punch are fixed-length, 
80-character records. When you use the &PUNCH control statement ina 
fixed-length EXEC file, EXEC scans only the first 72 columns of the 
EXEC. 


If you want to punch a word that contains more than eight characters, 
you must use the &BEGPUNCH control statement, which also, in 
fixed-length files, causes EXEC to punch data in columns 1 through 80. 
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Section 15. Using CMS EXECs with CMS Commands 


Whenever you create a CMS EXEC file you are, for all practical purposes, 
creating a new CMS command. When you enter a command line in the CMS 
environment, CMS searches for a CMS EXEC file with the specified 
filename before searching for a MODULE file or CMS command. You can 
place the names of your EXEC files in a synonym table and asSign nininun 
truncation values for the synonyms, just as you can for CMS command 
names. 


While many of your EXEC procedures may be very simple, others may be 
very long and complicated, and perform many of the housekeeping 
functions performed by CMS commands, such aS syntax checking, error 
message generation, and so on. 


Monitoring CMS Command Execution 


Many, or most, of your EXEC procedures may contain sequences of CMS 
commands that you want to execute. If your EXEC procedure contains no 
EXEC control statements, each command line is displayed and then the 
command is executed. If an error occurred, the CMS error message is 
displayed, followed by a return code in the format: 


+++ R(nnnnn) +++ 
where nnnnn is the nonzero return code from the CMS command. If the 
command is not a valid CMS command, or the command function for SET or 
QUERY is invalid and the implicit CP function is in effect, the return 
code is a -3: 

+++ R(-0003) +++ 
You may also receive this error return when you use a CP command without 
prefacing it with the CP command. If you enter an unknown CP command 
following "CP", you receive a return code of 1. 

If a command completes successfully, no return code is displayed. 

If you donot want to see the command lines displayed before 
execution, nor return codes following execution, you can use the EXEC 
control statement: 

SCONTROL OFF 


Or, if you want to see only the command lines that produced errors, and 
the resultant return codes, you can specify: 


&CONTROL ERROR 
Regardless of these settings of the &CONTROL statement, CMS error 
messages are displayed, as long as the value of &READFLAG is RT, and the 
terminal is displaying output. 

If you issue the LISTFILE, STATE, ERASE, or RENAME commands in an 
EXEC procedure, and you do not want to see the error message FILE NOT 
FOUND displayed, you can use the statement: 

SCONTROL NOMSG 


to suppress the display of these particular messages. 
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You can request that particular timing information be displayed 
during an EXEC's execution. If you want to display the time of day at 
which each command executes, you can specify: 


&CONTROL TIME 


Then, as each command line is displayed, it is prefaced with the time; 
for example: 


ECONTROL CMS TIME 
QUERY BLIP 


executes as follows: 


10:34:16 QUERY BLIP 
BLIP = * 


If you wish to see, following the execution of each CMS command, 
specific CPU timing information, such as the long form of the ready 
message, you can use the &TIME control statement. For example: 


&TIME ON 
QUERY BLIP 
QUERY FILEDEF 


might execute as: 


QUERY BLIP 
BLIP = OFF 
T=0.01/0.08 10:44:21 


QUERY FILEDEF 
NO USER DEFINED FILEDEF'S IN EFFECT 
T=0.01/0.04 10:45:26 


Handling Error Returns From CMS Commands 


In many cases, you want to execute a command only if previous commands 
were successful. For example, you would not want to execute a PRINT 
command to print a file if you had been unable to access the disk on 
which the file resided. There are two methods, using EXEC procedures, 
that allow you to monitor and control what happens following the 
execution of CMS commands. One method uses the EXEC control statement 
GERROR to transfer control when an error occurs; the other tests the 
special variable &RETCODE upon completion of a CMS command to determine 
whether that particular command completed successfully. 


USING THE & ERROR CONTROL STATEMENT 


When a CMS command is executed within a CMS EXEC, a return code is 
passed to the EXEC interpreter, indicating whether or not the command 
completed successfully. If the return code is nonzero, EXEC then 
activates the & ERROR control statement currently in effect. For 
example, if the following statement is included at the beginning of an 
EXEC file: 


GERROR &EXIT 
then, whenever a CMS command (or user program) completes with a nonzero 


return code, the SEXIT statement in the &SERROR statement is executed, 
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and the EXEC terminates processing. You might use a Similar statement 
in your EXECs to ensure that they do not attempt to continue processing 
in the event of an error. 


An &ERROR control statement can specify any executable statement. It 
may transfer control to ancther portion of the EXEC, or it may bea 
single statement that executes before control is returned to the next 
statement in the EXEC. For example: 


GSERROR &GOTO -EXIT 


transfers control to the label -EXIT, in case of any CMS error. The 
statement: 


GERROR &TYPE CMS ERROR 


results in the display of the message "CMS ERROR" before returning 
control to the statement following the command that caused the error. 


If you do not have an SERROR control statement in an EXEC, or if you 
specify &ERROR with no operands, EXEC takes no special action when a CMS 
command returns with an error return code. Specifying &ERROR with no 
operands is the same as specifying: 


GSERROR &CONTINUE 


Since an &ERROR control statement remains in effect for the remainder 
of the EXEC execution, or until another &ERROR control statement is 
encountered, you may use &ERROR &CONTINUE to restore default processing. 


USING THE &RETCODE SPECIAL VARIABLE 


An error return from a CMS command, in addition to calling an &ERROR 
control statement, also places the return code value in the EXEC special 
variable &RETCODE. Following the execution of any CMS command in an 
EXEC procedure, you can test whether or not the command completed 
without error. For example: 


TYPE ALPHA FILE A 
GIF SRETCODE -== 0 &EXIT 
TYPE BETA FILE A 
GIF GRETCODE x= 0 &EXIT 


Note: The value of &S&RETCODE is modified after the execution of each CMS 
command. 


The value of &RETCODE is affected by your own programs. If you 
execute a program in your EXEC using the LOAD and START (or FETCH and 
START) commands, or if you execute a MODULE file, then the &RETCODE 
special variable contains whatever value was in general register 15 when 
the program exited. If you are nesting EXEC procedures, then &RETCODE 
contains the value passed from the SEXIT statement of the nested EXEC. 


You can use the value of the return code, as well, to analyze the 
extent or the cause of the error and to set up an error analysis routine 


accordingly. For example, suppose you want to set up an analysis 
routine to identify return codes 1 through 11 and to exit from the EXEC 
when the return code is’ greater than 11. When a return code is 
identified, control is passed to a corresponding routine that attempts 
to correct the error. You could set up such an analysis routine as 
follows: 
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~ERRANAL 

SCNT = 0 

&LOOP 2 &CNT EQ 12 

SIF E&RETCODE EQ &CNT &GOTO -FIXECNT 
&CNT = &CNT + 1 


-FIXO &GOTO -ALLOK 
—-FIX1 


&GOTO -ALLOK 
-FIX2 


&GOTO -ALLOK 


-FIX11 


-ALLOK 


When the value of the &CNT variable equals the return code value in 
GERETCODE, the branch to the corresponding -FIX routine is taken. Each 
corrective routine performs different actions, depending on its code, 
and finishes at the routine labeled -ALLOK. 


You can, in some cases, determine the cause of a CMS command error 
and attempt to correct it in your EXEC. To do this, you must know the 
return codes issued by VM/SP commands. See VM/SP System Messages and 
Codes for a discussion of the return codes for VM/SP commands. In 
addition, the error messages and corresponding return codes are listed 
under the command descriptions for each CMS command in the VM/SP CMS 
Command and Macro Reference. 


As an example, all CMS commands that search for files issue a return 
code of 28 when a file is not found. If you want to test for a 
file-not-found condition in your EXEC, you might use statements sinilar 
to the following: 


SCONTROL OFF NOMSG 


TYPE HELP MEMO A 
SIF GRETCODE = 28 &GOTO -NOFILE 


Tailoring CMS Commands for Your Own Use 


You can create CMS EXEC procedures that simplify or extend the use of a 
particular CMS command. Depending on your applications, you can modify 
the CMS command language to suit your needs. You can create EXEC files 
that have the same names as CMS commands, and, since CMS locates EXEC 
files before MODULE files, the EXEC is found first. For example, the 
COPYFILE command, when used to copy CMS disk files, requires six 
operands. If you change only the filename when you copy files, you could 
create a COPY EXEC as follows: 
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&CONTROL OFF 

SIF SINDEX n= 3 &SKIP 2 

COPYFILE &1 &2 = &3 &2 = 

SEXIT 

COPYFILE &1 &2 &3 &4 &5 &6 &7 &8 &9 &10 &11 &12 &13 &14 &15 


If you always invoke the COPYFILE command using the truncation COPY, 
EXEC processes the command line for you, and if you have entered the 
three arguments, EXEC formats the COPYFILE command for you. If any 
other number of arguments is entered, the COPYFILE command is invoked 
with all the arguments as entered. 


CREATING YOUR OWN DEFAULT FILETYPES 


If you use special filetypes for particular applications and they are 
not among those that the CMS Editor supplies default settings for, but 
do require special editor settings, you can create a CMS EXEC to invoke 
the CMS Editor. The CMS EXEC can check for particular filetypes, and if 
it finds them, stack the appropriate EDIT subcommands. If you name this 
EXEC procedure E EXEC, then you can bypass it by using a longer form of 
the EDIT command. The following is a sample E EXEC: 


&CONTROL OFF 

SIF SINDEX GT 1 &SKIP 2 

EDIT &1 SCRIPT 

SEXIT 

SIF 6&2 EQ TABLE &GOTO -TABLE 
SIF 62 EQ CHART &GOTO -CHART 
GIF &2 EQ EXEC &GOTO -EX 

GIF &2 EQ SYSIN &GOTO -SYSIN 
-NORM EDIT &1 &2 &3 &4 &5 &6 
SEXIT 

-TABLE &BEGSTACK 

IMAGE ON 

TABS 1 10 20 

CASE M 

& END 

EDIT &1 &2 &3 (LRECL 20 
SEXIT 

—CHART &BEGSTACK 

CASE M 

IMAGE ON 

& END 

EDIT &1 &2 §&3 

SEXIT 

-EX 

EDIT 61 &2 &3 (LRECL 130 
SEXIT 

-SYSIN &BEGSTACK 

TABS 1 10 16 31 36 41 46 69 72 80 
SERIAL ON 

TRUNC 71 

VERIFY 72 

& END 

EDIT &1 &2 &3 

SEXIT 


This CMS EXEC defines special characteristics for filetypes CHART, 
TABLE, and SYSIN, and defaults an EXEC file to 130-character records. 
If only one argument is entered, it is assumed to be the filename of a 
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SCRIPT file. Since the editor is invoked from within the EXEC, control 
returns to EXEC after you use the FILE or QUIT subcommands during the 
edit session. You must use the SEXIT control statement so that the EXEC 
does not continue processing, and execute the next EDIT command in the 
file. 
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Section 16. Refining Your CMS EXEC Procedures 


This section provides supplementary information for writing complex EXEC 
procedures. Although the EXEC interpreter resembles, in some aspects, a 
high-level programming language, you do not need to be a programmer to 
write EXECs. Some of the techniques suggested here, for example, on 
annotating and writing error messages, are common programming practices, 
which help make programs self-documenting and easier to read and to use. 


Annotating CMS EXEC Procedures 


Lines in a CMS EXEC file that begin with an asterisk (*) are commentary 
and are treated as comments by the EXEC interpreter. You can use * 
Statements to annotate your EXECs. If you write EXECS frequently, you 
may find it convenient to include a standard comment at the beginning of 
each EXEC, indicating its function and the date it was written, for 
example: 


* EXEC TO HELP CONVERT LISTING FILES 
* INTO SCRIPT FILES 
* J. BEAN 10/18/75 


You can also use single asterisks or null lines to provide spacing 
between lines in an EXEC file to make examining the file easier. 


In an EXEC, you cannot place comments on the same line with an 
executable statement. If you want to annotate a particular statement or 
group of statements, you must place the comments either above or below 
the lines you are annotating. 


A good practice to use, when writing EXECs, is to set them up to 
respond to a ? (question mark) entered as the sole argument. FOL 
example, an EXEC named FSORT might contain: 


ECONTROL OFF 
SIF GINDEX = 1 &IF &1 = ? &GOTO -TELL 


-TELL &BEGTYPE 
CORRECT FORM IS * FSORT USERID <VADDR> ! 


PRINTS AN ALPHABETIC LISTING OF ALL FILES ON THE SPECIFIED 
USER'S DISK. IF A VIRTUAL ADDRESS (VADDR) IS NOT 
SPECIFIED, THE USER'S 191 IS THE DEFAULT. 

& END 


You may also wish to anticipate the situation in which a user might 
enter an EXEC name with no arguments for an EXEC that requires 
arguments: 
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SIF SINDEX 
SIF EINDEX 


0 &GOTO -HELP 
1 &IF &1 = ? &GOTO -TELL 


SEXIT 

-HELP &BEGTYPE 
CORRECT FORM IS *§ COPY OLDFN OLDFT NEWFN ! 
TYPE * COPY ? * FOR MORE INFO 

& END 

S EXIT 

-TELL &BEGTYPE 
CORRECT FORM IS ' COPY OLDFN OLDFT NEWFN ! 
USES COPYFILE COMMAND TO CHANGE ONLY THE FILENAME 

& END 

SEXIT 


This type of annotating is especially useful if you share your disks or 
your CMS EXECs with other users. 


Error Situations 


It is good practice, when writing CMS EXECs, to anticipate error 
Situations and to provide meaningful error or information messages to 
describe the error when it occurs. The following error situations, and 
suggestions for handling them, have already been discussed: 


e Errors in invoking the EXEC, either with an improper number of 
arguments, or with invalid arguments. (See "Arguments" in "Section 
14. Building CMS EXEC Procedures.") 


e Errors in CMS command processing that can be detected with an &ERROR 
control statement or with the G&RETCODE special variable. (See 
"Handling Error Returns from CMS Commands" in "Section 15. Using CMS 
EXECS With CMS Commands.") 


Many different kinds of errors tay also occur, in the processing of 
your CMS EXEC control statements. EXEC processing errors, such 4S an 
attempt to branch to a nonexistent label or an invalid syntax, are 
"unrecoverable" errors. These errors always terminate CMS EXEC 
processing and return your virtual machine to the CMS environment or to 
the calling EXEC procedure or program. The error messages produced by 
EXEC, and the associated return codes, are described in the VM/SP System 
Messages and Codes 


WRITING ERROR MESSAGES 


One way to make your CMS EXECS more readable, especially if they are 
long EXECs, is to group all of your error messages in one place, 
probably at the end of the EXEC file. You may also wish to number your 
messages and associate the message number with a label number anda 
return code. For example: 
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SIF &CT > 100 &GOTO -ERR100 
SIF &CT < 0 &GOTO -ERR200 


SIF ERETCODE EQ 28 &GOTO -ERR300 


—-ERR100 

ETYPE COUNT TOO HIGH 

SEXIT 100 

~ERR200 

&ETYPE COUNT TOO LOW 

SEXIT 200 

-~ERR300 

ETYPE &1 &2 NOT ON DISK ‘Cf. 
&SEXIT 300 


There is a facility, available in the EXEC processor, which allows you 
to write error messages that use the standard VM/SP message format, with 
an identification code and message number, as well as message text. 
When you use the &EMSG or &BEGEMSG control statement, the EXEC 
interpreter scans the first token and checks to see if the seventh (and 
last character) is an I, E, or W, representing information, error, or 
warning messages, respectively. If so, then the message is displayed 
according to the CP EMSG setting (ON, OFF, CODE, or TEXT). For example, 
if you have the statement: 


G&EMSG ERROR1E BAD ARGUMENT * &1 § 


the ERROR1E is considered the code portion of the message and BAD 
ARGUMENT is the text. If you have issued the CP command: 


cp set emsg text 


when this &EMSG statement is executed it may display: 


BAD ARGUMENT * PRNIT 
where PRNIT is the argument that is invalid. 

When you use &EMSG (or &BEGEMSG, which allows you to display error 
messages of unscanned data), the code portion of the message is prefixed 
with the characters DMS, when displayed. For example: 

&BEGEMSG 
ERROR2E INCOMPATIBLE ARGUMENTS 
& END 
displays when the EMSG setting is ON: 
DMSERROR2ZE INCOMPATIBLE ARGUMENTS 
You should use the &BEGEMSG control statement when you want to display 


lines that have tokens longer than eight characters; however, no 
variable substitution is performed. 
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Debugging CMS EXEC Procedures 


If you have difficulty getting an EXEC procedure to execute properly, or 
if you are modifying an existing EXEC and wish to test it, there are a 
couple of simple techniques that you can use that may save you time. 


One is to place the &CONTROL ALL control statement at the top of your 
EXEC file. When &CONTROL ALL is in effect, allthe EXEC’ control 
statements are displayed before they execute, as well as the CMS command 
lines. One of the advantages of using this method is that the line is 
displayed after it is scanned, so that you can see the results of symbol 
and variable substitution. 


"Stacking CMS EXEC Files" in “Section 14. Building CMS EXEC 
Procedures" described a PREFIX EXEC, which changes’ the prefixes of 
groups of files. If the EXEC had an S&CONTROL ALL statement, it might 
execute as follows: 


prefix pt ag 

SCONTROL ALL 

SLNAME = &CONCAT PT * 

LISTFILE PT* SCRIPT * ( EXEC 

EXEC CMS &STACK 

&LOOP -END &SREADFLA EQ CONSOLE 

LOOP UNTIL: STACK EQ CONS 
GREAD VARS &NAME &TYPE &MOD 

S&SUFFIX = &SUBSTR PTA 3 6 

ENEWNAM = ESCONCAT AG A 

RENAME PTA SCRIPT A1 AGA SCRIPT Al 
SIF 0 EQ O &SKIP 

&SKIP 

LOOP UNTIL: STACK EQ CONS 
EREAD VARS &NAME &TYPE &MOD 

&SUFFIX = &SUBSTR PTB 3 6 

ENEWNAM = &CONCAT AG B 

RENAME PTB SCRIPT A1 AGB SCRIPT A1 
&IF 0 EQ O &SKIP 

&SKIP 

LOOP UNTIL: CONSOLE EQ CONS 
R; 


You can see from this execution summary that the files named PTA SCRIPT 
and PTB SCRIPT are renamed to AGA SCRIPT and AGB SCRIPT. Notice that 
the €LOOP statement results in a special LOOP UNTIL statement in the 
execution summary, which indicates the condition under which the loop 
executes. 
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USING CMS SUBSET 


When you are using the CMS Editor to create or modify a CMS EXEC 
procedure, you can test the EXEC in the CMS subset environment, as long 
as the EXEC does not issue any CMS commands that are invalid in CMS 
subset. 


Before entering CMS subset with the CMS subcommand, you must issue 
the SAVE subcommand to write the current version of the EXEC onto disk; 
then, in CMS subset, execute the EXEC. For example: 


edit new exec 

NEW FILE: 

EDIT: 

input 

INPUT: 

Sa = &1 + &2 + &3 
&type answer is &a 


EDIT: 

save 

EDIT: 

cms 

CMS SUBSET 
new 34 56 899 
ANSWER IS 989 


If the EXEC does not execute properly, you can return to the edit 
environment using the RETURN command, modify the EXEC, reissue the SAVE 
and CMS subcommands, and attempt to execute the EXEC again. 
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SUMMARY OF CMS EXEC INTERPRETER LOGIC 


The following information is provided for those who have an interest in 
how the CMS EXEC interpreter works. It may help you in debugging your 
EXEC procedures if you have some idea of how processing is done by EXEC. 
When an EXEC file is invoked for execution, the EXEC interpreter 
examines each statement and analyzes it, according to the following 
sequence: 


1. If the first nonblank character of the line is an *, the line is 
counted and ignored. 


2. Null lines, except as a reponse to an &READ statement, are also 
counted and ignored. 


3. The line is scanned, and nonblank character strings are placed in 
tokens. 


4%. All EXEC special variables, and then all user variables, except for 
those that appear as the target of an aSsignment statement, are 
substituted. 


6. All blank tokens (resulting from the substitution of undefined 
symbols) are discarded. 


7. j%$«If the first nonblank character is a hyphen (-), indicating a 
label, the next token is considered the first token. 


8. If the first logical token does not begin with an ampersand (&), 
the line is passed to CMS for execution. The return code from CMS 
is placed in the special variable &RETCODE. 


9. If the first logical token begins with an ampersand (&) EXEC 
interprets the statement. 


10. If a statement is syntactically invalid and can be made valid by 
adding a token of blanks at the end, EXEC adds blanks, for example: 


E&BLANK = 
GETYPE 
&ELOOP 3 &X NE 
All of the above are valid EXEC control statements. 
11. EXEC executes the statement. If no error iS encountered, control 
passes to the next logical statement. If an error is encountered, 
EXEC terminates processing. 


Note: For information on the EXEC 2 interpreter, see VM/SP EXEC 2 
Reference. 
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Section 17. Writing CMS EDIT Macros 


If you have a good knowledge of the CMS EXEC facilities and an 
understanding of the CMS Editor, you may wish to write edit macros. An 
edit macro is simply an EXEC file that contains a sequence of EDIT 
subcommands. Edit macros should only be invoked from the edit 
environment. An edit macro may contain a simple sequence of EDIT 
subcommands, or its execution may be dependent on arguments you enter 
when you invoke it. This section provides information on creating edit 
macros, suggestions on how to manipulate the console stack, and some 
examples of macros that you can create and use. 


Creating CMS Edit Macro Files 


An edit macro must have a filename beginning with a dollar sign ($) and 
a filetype of EXEC. Rules for file format, scanning and token 
substitution are the same as for all other EXEC files. A macro file may 
contain: 


e EDIT subconmmands 
e CMS EXEC control statements 
e CMS commands that are valid in CMS subset 


When you create an edit macro that accepts arguments, you should be 
sure to check the validity of the arguments, and issue appropriate error 
messages. If you are writing an edit macro to expect arguments, you nust 
keep in mind that the macro command line is scanned, and that any data 
items you enter are padded or truncated into eight-character tokens. 
Tokens are always translated to uppercase letters. 


You should annotate all of your macro files, and provide a response 
to a question mark (?) entered as the sole argument (as described under 
"Annotating CMS EXEC Procedures" in "Section 16. Refining Your CMS EXEC 
Procedures") . 


How CMS Edit Macros Work 


Since an edit macro is a CMS EXEC file, it is actually executed by the 
CMS EXEC interpreter, and not by the CMS Editor. The CMS EXEC 
interpreter can only execute EXEC control statements and CMS commands. 
The only way to issue an EDIT subcommand from an EXEC file is to stack 
the subcommand in the console stack, so that when the editor is invoked, 
or receives control, it reads the subcommand(s) from the console stack 
before accepting input lines from the terminal. For example: 


&STACK CASE M 
&STACK RSCFM V 
EDIT &1 CHART At 


When the EDIT command is invoked from this EXEC, the CMS Editor reads 
the subcommands from the stack and executes then. 


To execute these same subcommands from an edit macro file, you must 
use the same technique; that is, you must place the subcommands in the 
console stack, for example: 
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&BEGSTACK 
CASE M 
RECFA V 
&END 

S EXIT 


If this were an EXEC file named $VARY, you might execute it from the 
edit environment as follows: 


edit test file 
NEW FILE. 
EDIT: 

$vary 


Stacked subcommands are executed only when the CMS EXEC completes its 
execution, either by reaching the end of the file, or by processing an 
SEXIT statement. 


When you stack EDIT subcommands, you can use the &STACK and &BEGSTACK 
control statements. If you are stacking a subcommand that uses a 
variable expression, you must use the &STACK control statement, rather 
than the &BEGSTACK control statement. The following EXEC, named $T, 
displays a variable number of lines and then restores the current line 
pointer to the position it was in when the EXEC was invoked: 


&CONTROL OFF 

SIF GINDEX EQ 0 &GOTO -ERR 

&CHECK = &DATATYPE &1 

SIF &CHECK NE NUM &GOTO -ERR 

ESTACK TYPE 6&1 

&6UP = &1- 1 

ESTACK UP &UP 

GSEXIT 

-ERR &TYPE CORRECT FORM IS < $T N > 
SEXIT 1 


This edit macro uses the built-in function §DATATYPE to check that a 
numeric operand is entered. 


CMS commands in an edit macro are executed as they are read by the 
CMS EXEC interpreter, just as they would if the EXEC were invoked in the 
CMS environment. You could create a $TYPE edit macro, for example, that 
would allow you to display a file from the edit environment: 


&CONTROL OFF 
TYPE &1 &2 &3 &4 &5 &6 &7 


Or you might create a $STATE EXEC that would verify the existence of 
another file: 


&CONTROL OFF 
STATE &1 &2 &3 


In both of these examples, the macro file invokes the CMS’ command. 
Macros like these can eliminate having to enter CMS subset environment 
to execute one or two simple CMS commands. You must be careful, though, 
not to execute any CMS command that uses the storage occupied by the 
editor. Only commands that are valid in CMS subset are valid in an edit 
macro. 
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THE CONSOLE STACK 


When you write an edit macro, you want to be sure that there are no EDIT 
subcommands in the stack that could interfere with the execution of the 
subcommands stacked by the macro file. Your macro should check whether 
there are any lines in the stack, and if there are, it should clear then 
from the stack. For example, you might use the lines: 


SIF GREADFLAG EQ CONSOLE &SKIP 2 
DESBUF 
STYPE STACKED LINES CLEARED BY 0 


The message "STACKED LINES CLEARED BY macro name" is issued by the edit 
macros distributed with the VM/SP System. You may also want to use 
this convention in your macros, to alert a user that the console stack 
has been cleared. 


Top of File and End of File 


When an edit macro is invoked and the current line pointer is positioned 
at the top of the file or at the end of the file, the editor stacks a 
token in the console stack. If the line pointer is at the top of the 
file, the token stacked is "TOF"; if the line pointer is at the end of 
the file the token stacked is "EOF". If you write an edit macro that 
does not check the status of the console stack, and the macro is invoked 
from the top or the end of the file, you receive the message: 


?EDIT: TOF 
Or: 
?EDIT: EOF 
The editor does not recognize these tokens as valid subcommands. 

You may want to use these tokens’ to test whether the EXEC is invoked 
from the top or end of the file. If you want to clear these tokens in 
case the macro has been invoked from the top or end of the file, you 
Bight use the statement: 


SIF SREADFLAG EQ STACK &READ VARS 


which clears the token from the stack. 


Stacking LIFO 


If you do not want to clear the console stack when you execute an edit 
macro, you can stack all of the subcommands using the LIFO (last-in 
first-out) operand of the &STACK and &BEGSTACK control statements. For 
example, suppose $FORMAT is the name of the following edit macro: 


&BEGSTACK LIFO 
TABSET 3 10 71 
TRUNC 71 
PRESERVE 

& END 
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When this edit macro is executed, the subcommands are placed in the 
console stack in front of any existing lines. For example, if this macro 
were invoked: 


$format#input 


the subcommands would execute in the following order: PRESERVE, TRUNC, 
TABSET, INPUT. If the subcommands were stacked FIFO (first-in 
first-out), the default, the INPUT subcommand would be the first to 
execute (Since it is the first command in the stack) and the remaining 
subcommands would be read into the file as input lines. 


Error Situations 


If a CMS EXEC processing error occurs during the execution of an edit 
Macro, the editor clears the console stack and issues the "STACKED LINES 
CLEARED" message. A CMS EXEC processing error is one that causes the 
error message DMSEXTO72E: 


ERROR IN EXEC FILE filename, LINE nnnn - description 


These errors cause the CMS EXEC interpreter to terminate processing. Any 
stacked subcommands are cleared before the editor regains control, so 
that none of the subcommands are executed, and the file remains 
unchanged. 


You should also ensure that any error handling routines in your edit 
Macros clear the stack if an error occurs. Otherwise, the editor may 
begin reading invalid data lines from the stack and attempt to execute 
them as EDIT subcommands. 


You should not interrupt the execution of an edit macro by using the 
Attention or Enter key, and then entering a command or data line. 
Results are unpredictable, and you may inadvertently place unwanted 
lines in the stack. 


If your edit macro contains a CMS command that is invalid in the CMS 
subset environment, you receive a return code of -2. 


The maximum number of lines that you can stack in an edit macro 
varies according to the amount of free storage that is available to CMS 
at the time of the stacking request. If you stack too many lines, the 
editor terminates abnormally. 


Notes on Using EDIT Subcommands 


You can use any EDIT subcommand in a macro file, and there is one 
special subcommand whose use only haS meaning in a macro: the STACK 
subcommand. For the most part, there is not any difference between 
executing an EDIT subcommand from the edit environment, or from an EXEC 
edit macro. You do have to remember, however, that if you want a 
variable symbol ona subcommand line, you must stack that subcommand 
using the &STACK control statement rather than following an &BEGSTACK 
control statement. 


Listed below are some notes on using various EDIT subcommands in your 


macro files. You may find these notes useful when you design your own 
macros. 
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PRESERVE, VERIFY, AND RESTORE: Often, you may want to create an edit 
macro that alters the characteristics of a file (format, tab settings, 
and so on). To ensure that the original characteristics are retained 
when the macro has finished executing, you can stack the PRESERVE 
subcommand as the first subcommand in the stack, and the RESTORE 
subcommand as the last subcommand in the stack: 


&BEGSTACK 

PRESERVE 

CASE 4 

I A lowercase line 
RESTORE 

& END 


The PRESERVE and RESTORE subcommands save and reinitialize the settings 
for the CASE, FMODE, FNAME, IMAGE, LINEMODE, LONG, RECFM, SERIAL, SHORT, 
TABSET, TRUNC, VERIFY, and ZONE subcommands. 


In an edit macro that issues many subcommands that display lines in 
response to CHANGE or LOCATE subcommands, you may want to turn the 
verification setting to OFF to suppress displays during the execution of 
the edit macro: 


GSBEGSTACK 
PRESERVE 
VERIFY OFF 


RESTORE 
& END 


You would particularly want to turn verification off for a macro that 
executes in a loop or that issues a global request. If you want a line 
or series of lines displayed, you can use the TYPE subcommand. 


If you have verification set off in an edit macro, then when you 
execute it you may not receive any indication that the edit macro 
completed execution. The keyboard unlocks to accept your next EDIT 
subcommand from the terminal. To indicate that the macro is finished, 
you can stack, as the last subcommand in the procedure, a TYPE 
subcommand, to display the current line. Or, if you write an edit macro 
that terminates when an end-of-file condition occurs the EOF: message 
issued by the editor may indicate the completion of the macro. 


INPUT, REPLACE: To change from edit mode to input mode in an edit macro, 
you can use the INPUT and REPLACE subcommands. In a_ fixed-length EXEC 
file, you must stack these subcommands using the 6&STACK control 
statement: 


&STACK INPUT 
ESTACK REPLACE 
If you use either of these subcommands following an 6&BEGSTACK control 
statement, the subcommand line is padded with blanks to the line length 
and the result is a line of blanks inserted into the file. 
In a variable-length EXEC file, lines are not padded with blanks, so 
the INPUT and REPLACE subcommands with no data line execute the sane 


following an &BEGSTACK control statement as they do when stacked with 
the &STACK control statement. 


Section 17. Writing CMS Edit Macros 345 


Going From Input Mode to Edit Mode: To stack a null line in an edit 
macro, to cause the editor to leave input mode, you must use the &STACK 
control statement with no other tokens, as follows: 


ESTACK 


CHANGE, DSTRING, LOCATE: If you want to use the CHANGE, DSTRING, or 
LOCATE subcommands in an EXEC, you must take into account that when you 
stack any of these subcommands using the &STACK control statement, all 
of the character strings on the line are truncated or padded to eight 
characters. Also, if you want to use a variable value for a character 
string, you are limited to eight characters, all uppercase. 


For example, if a macro is used to locate a character string and 
delete the line on which it appears, the LOCATE subcommand has a 
variable symbol: 


ESTACK LOCATE /&1 
ESTACK DEL 


IMAGE, TABSET, OVERLAY: The TABSET and OVERLAY subcommands allow you to 
set margins and column stops for records in a file andto overlay 
character strings in particular positions. For example, the following 
macro places a vertical bar in columns 1, 15, 40, and 60 for all records 
in the file from the current line to the end of the file: 


&BEGSTACK 
PRESERVE 

IMAGE ON 

TABSET 1 15 4O 60 
REPEAT * 

O |->|I->1->1] 
RESTORE 

& END 


In the above example, the "->" symbol represents a tab character 
(X'05"). To create this EXEC, you can either issue the EDIT subcommand;: 


image off 


and use the Tab key (or equivalent) on your terminal when you enter the 
line, or you can enter some other character and use the ALTER subcommand 
to alter that character to a xXx'05'. 


If you want to overlay only one character string in a particular 
position in a file, you can use the TABSET subcommand to set that column 
position as the left margin, and then use the OVERLAY subcommand, as 
follows: 


&CONTROL OFF 
EBEGSTACK 
PRESERVE 
VERIFY OFF 
TRUNC * 

TABS 72 

GEND 

ESTACK REPEAT 6&1 
& BEGSTACK 
OVERLAY C 
RESTORE 

& END 
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If you name this file $CONT EXEC, and if you invoke it with the line: 
$cont 3 


then the OVERLAY subcommand is executed on three successive lines, to 
place the continuation character "C" in column 72. 


THE STACK SUBCOMMAND 


The STACK subcommand allows you to stack up to 25 lines from a file in 
the console stack. The lines are not deleted from the file, but the line 
pointer is moved to point to the last line stacked. 


You can also use the STACK subcommand to stack EDIT subcommands. You 
might do this if there were subcommands that you wanted to place in the 
stack to execute after all the subcommands stacked by the EXEC had 
executed. 


These techniques are used in the two edit macros that are distributed 
with the VM/SP system: $MOVE and $DUP. If you want to examine these 
files for examples of how to use the STACK subcommand, you can display 
the files by entering, from the CMS environment: 

type $move exec * 
type $dup exec * 


An additional use of the STACK subcommand is shown in "An Annotated 
Edit Macro." 
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An Annotated Edit Macro 


The edit macro shown below, $DOUBLE, can be used to double space a CMS 
file. Regardless of where the current line pointer is, a blank line is 
inserted in the file following every existing line. The statements in 
the edit macro are separated into groups; the number to the left of a 
Statement or group of statements indicates an explanatory note. The 
humbers are not part of the EXEC file. 


1 SCONTROL OFF 


2 SIF GINDEX 


1 &IF &1 ? &GOTO -TELL 


3 SIF &INDEX = 1 &I1F &1 = TWO &GOTO -LOOP 
4 SIF &INDEX NE O &GOTO -TELL 
5 SIF SREADFLAG EQ STACK &READ VARS &GARB 


6 &STACK 
&STACK PRESERVE 
SSTACK VERIFY OFF 


7 SSTACK BOTTOM 
&STACK I XXXXXXXX 
&STACK TOP 


Notes: 

1 The &CONTROL statement suppresses the display of CMS commands, in 
this case, the DESBUF command. 

2 The first SIF checks that there is only one operand passed in the 
$DOUBLE command. The second &IF checks whether $DOUBLE has been 
invoked with a question mark (?). If both &IFs are true, control 
is passed to the statement at the label -TELL. &TYPE control 
Statements at -TELL explains what the macro does. 

3 The second &IF statement checks whether $DOUBLE has’ been invoked 
with the argument TWO, which indicates that the macro has executed 
itself, so the subcommands that initialize the file are stacked 
only once. 

| There are three ways to properly invoke this edit macro: with a ?, 
with the argument TWO, or with no arguments. The third 6&IF 
statement checks for the (no arguments) condition; if the macro is 
invoked any other way, control is passed to the label -TELL, which 
explains the macro usage. 

5 The SREADFLAG special variable is checked. If $DOUBLE is executed 
at the top or at the end of the file, the token TOF or EOF is in 
the stack, and should be read out. 

6 A null line is placed in the console stack for loop control (see 
Note 9.) The PRESERVE and VERIFY subcommands are stacked so that 
the editor does not display each line in the file as it executes 
the stacked subcommands. 

7 The BOTTOM, INPUT, and TOP subcommands initialize the file by 
placing a marker at the bottom of the file, and then positioning 
the current line pointer at the top of the file. 
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11 
12 


13 


13 


-LOOP 
&BEGSTACK 
NEXT 
STACK 1 
INPUT 

& END 


SREAD ARGS 
SIF .&1 = . &SKIP 
SIF &1 EQ XXXXXXXX ESKIP 2 


—-ENDLOOP &STACK $DOUBLE TWO 
S EXIT 


DESBUF 

& BEGSTACK 
UP 2 

DEL 3 
TYPE 
RESTORE 
SEND 


SEXIT 


-TELL 

SIF GREADFLAG EQ STACK &READ VARS 
&BEGTYPE 

CORRECT FORM IS: $DOUBLE 


THIS EXEC DOUBLE SPACES A FILE BY INSERTING 

A BLANK LINE FOLLOWING EVERY LINE IN THE FILE 
EXCEPT THE LAST. 

& END 


The NEXT, STACK, and INPUT subcommands are going to be repeated for 
each line in the file. The INPUT subcommand with no data line 
stacks a null line. Note that in order for $DOUBLE to execute this 
subcommand properly, $DOUBLE EXEC must have fixed-length records. 
Each line is stacked, with the STACK subcommand;. this stacked line 
is checked in the read loop (Note 9). When the stacked line is 
equal to the marker, XXXXXXXX, it indicates that the end of the 
file has been reached. 

These lines check for an end of file, which occurs when the line 
containing the marker is read. The first time this loop is 
executed, the stack contains the null line (statement 6), so the 
check for the marker is skipped. 

The last subcommand stacked is $DOUBLE TWO, which re-invokes 
S$DOUBLE, but causes it to skip the first sequence of subcommands. 
The &EXIT statement causes an exit from $DOUBLE, so that all the 
EDIT subcommand stacked thus far are executed. 

When the marker is read in, the EXEC clears the stack, moves the 
current line pointer to point to the null line added above the 
Marker, and deletes that line, the marker, and the null line that 
was inserted following the marker. The RESTORE subcommand restores 
editor settings. 

This edit macro is self-documenting. If $DOUBLE is invoked with a 
question mark, or invoked with an argument, information regarding 
its proper use is displayed. 
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User-Written Edit Macros 


You can create the edit macros shown below, for your own use in CMS. 
You may want to refer to them as examples when you are learning to write 
your own macros. The macros have not been formally tested by IBM; they 
are presented for your convenience only. 


$MACROS 
The $MACROS edit macro verifies the existence of and describes the usage 
of edit macros. If you enter: 

$macros 


it lists the filenames of all the edit macros on your accessed disks. 
If you enter: 


$macrosS namel name2 


it displays, for each valid macro name entered, the macro format and 
usage. (This macro assumes that all macros have heen designed to 
respond to a ?._ request.) The format of the $MACROS edit macro 
instruction is: 


nent ee dg Oe gn Oe pe et ge ae Ea ea ee ae ea ee oe eS ae ee ne re ey 
| $MACROS | [filename1 [filename2 [ filenamen ]}] i 
| 
filename is the filename(s) of macro files whose usage is to be 


displayed. If filename is omitted, the filenames of all 
available macro files are listed. 


To create $MACROS, enter: 
edit $macros exec 


and in input mode, enter the following: 
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SCONTROL OFF 

SIF SINDEX EQ 1 SIF &1 EQ ? &GOTO -TELL 
SIF SINDEX GT 0 &GOTO -PARTIC 

x 


SBEGTYPE ALL 

EXEC FILES STARTING WITH A DOLLAR-SIGN ARE AS FOLLOWS. 
FOR INFORMATION ON ONE OR MORE OF THEM, TYPE: 
$MACROS FILENAME1 <FILENAME2> 

& END 

LISTF $* EXEC * (NOHEADER FNAME) 

& EXIT 

* 

—~PARTIC &TRIP = 0 

SINDEX1 = 0 

* 


&LOOP -ENDLOOP &SINDEX 

SINDEX1 = SINDEX1 + 1 

&SUB = &SUBSTR S&INDEX1 1 1 

SIF &SUB EQ $ &GOTO -—-STATIT 
STYPE S&INDEX1 IS INVALID 

STRIP = 1 

&GOTO -ENDLOOP 

-STATIT STATE S&INDEX1 EXEC * 

SIF ERETCODE EQ O &GOTO -CALLIT 

STYPE SEINDEX1 NOT FOUND 

&TRIP = 1 

&GOTO -ENDLOOP 

-CALLIT EXEC S&INDEX1 ? 

-ENDLOOP 

* 


SEXIT &TRIP 
€ 


-TELL &BEGTYPE 

"SMACROS* HANDLES THE "$MACROS! REQUEST. 
TYPE ‘S$MACROS* ALONE FOR MORE INFORMATION. 
& END 

S EXIT 


SMARK 


The $MARK edit macro inserts from one to six characters, starting with 
the current line and in the column specified, for a specified number of 
records. If there is data already in the columns’ specified, it is 
overlayed. If you enter: 


$nark 


the macro places an asterisk (*) in column 72 of the current line. If 
you enter: 


$mark 10 30 abc 
the macro places the string ABC beginning in column 30 in each of ten 


records, beginning with the current record. The format of the $MARK 
edit macro instruction is: 
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where: 


n indicates the number of consecutive lines, starting with the J 
record currently being pointed to, that will be marked. If n is 
not specified, 1 is assumed, and the other default values are 
also assumed. 


col indicates the starting column in each record where the character 
string is to be inserted. The default is column 72. 


char indicates from one to six characters to be inserted in each 
record. The default is an asterisk (*). 


To create $MARK, enter: 
edit $mark exec 
and in input mode, enter the following: 


&CONTROL OFF 

SIF SINDEX EQ 1 SIF &1 EQ ? &GOTO -TELL 
SIF &INDEX GT 3 &GOTO —-BADPARN 

SINDEX1 = 1 

SIF S&INDEX GT 0 SINDEX1 = &1 

SIF SINDEX1 LT O &GOTO -BADPARSM 

GINDEX2 = 72 

SIF SINDEX GT 1 &INDEX2 = 6&2 

SIF SEINDEX2 LT O &GOTO -BADPARM 

SIF &INDEX2 GT 133 &GOTC -BADPARM 


&CHAR = * 

SIF SINDEX EQ 3 SCHAR = 8&3 

&LEN3 = &LENGTH &CHAR | 
SIF &LEN3 GT 6 &GOTO -BADP ARM -) 


&STACK LIFO RESTORE 

&SSTACK LIFO OVERLAY &CHAR 

SSTACK LIFO REPEAT SINDEX1 

&STACK LIFO TABS &INDEX2 

&BEGSTACK LIFO 

IMAGE ON 

TRUNC * 

VERIFY OFF 

LONG 

PRESERVE 

& END 

SEXIT 

* 

—-BADPARM &BEGTYPE 

INVALID $MARK OPERANDS 

& END 

SEXIT 1 

* 

-TELL SBEGTYPE 

CORRECT FORM IS: $MARK <N <COL <CHAR>>> 
PUTS A 1-6 CHARACTER STRING IN COLUMN 'COL* OF 'N* LINES, STARTING 
WITH THE CURRENT LINE. THE NEW CURRENT LINE IS THE LAST LINE 
MARKED. DEFAULTS ARE: N=1; COL=72; CHAR=*. 
& END 

SEXIT 
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SPOINT 


The $POINT edit macro positions the current line pointer at the 
specified line number. The line numbers must be in cclumns 73 through 80 
and padded with zeros. For example, if you enter: 


$point 800 


the current line pointer is positioned at the line that has the serial 
number 00000800 in columns 73 through 80. The format of the $POINT 
macro instruction is: 


Cen oe ee ee 
| S$POINT | key | 
We es es SE eee 


where: 

key is a one- to eight-character line number. If the specified key 
is less than eight characters long, it is padded with leading 
zeros. 


To create $POINT, enter: 
edit $point exec 
and in input mode, enter the following: 


SCONTROL OFF 
SIF SINDEX EQ 0 &GOTO -TELL 

SIF SINDEX EQ 1 SIF &1 EQ ? &GOTO -TELL 
SIF SINDEX GT 1 &GOTO -BADPARM 
&KEYL = &LENGTH &1 

SINDEX1 = 8 - &KEYL 

&Z = ESUBSTR 00000000 1 SINDEX1 
&1 = SCONCAT &Z &1 

&STACK LIFO RESTORE 

SSTACK LIFO FIND &1 

&BEGSTACK LIFO 

TOP 

TABS 73 

IMAGE ON 

LONG 

PRESERVE 

SEND 

SEXIT 

* 

-BADPARM &BEGTYPE ALL 

INVALID $POINT OPERANDS 

& END 

SEXIT 1 

* 


-TELL &BEGTYPE ALL 

CORRECT FORM IS: $POINT KEY 

IF "KEY' CONTAINS LESS THAN 8 CHARACTERS, IT IS PADDED WITH LEADING 
ZEROS. THE FILE IS THEN SEARCHED FROM THE TOP FOR 'KEY* IN COLUMNS 
73-80. 

& END 

SEXIT 
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$SCOL 


The $COL edit macro inserts, after the current record in the file, a 
line containing column numbers (that is, 1, 6, 11, .~.-., 76). The format 
of the $COL macro instruction is: 


|: sp ge es ee ee a, eee Ge ee ee Ps ee a a gee ee ee ae ee ee Se 
| $coL | | 
_—————E— 


No operands are used with $COL. If any arguments are entered, the macro 
usage is explained. 


To create $COL, enter: 
edit $col exec 
and in input mode, enter the following: 


&CONTROL OFF 

G&IF &SINDEX NE 0 &GOTC -TELL 
&STACK LIFO RESTORE 

&ESTACK LIFO 

&BEGSTACK LIFO ALL 

1 6 11 #16 21 26 31 36 41 46 51 56 61 66 71 76 
& END 

ESTACK LIFO INPUT 

&BEGSTACK LIFO 

TRUNC * 

VERIFY OFF 

LONG 

PRESERVE 

&END 

GS EXIT 

* 

~TELL &BEGTYPE 

CORRECT FORM IS: $COL 
INSERTS A LINE INTO THE FILE SHOWING COLUMN NUMBERS. 
& END 

&EXIT 


354 IBM VM/SP CMS User's Guide 


Part 4. The HELP Facility 


The CMS HELP facility provides an on-line display of documentation for 
CP and CMS messages and commands, EXEC and EXEC 2 statements, and EDIT, 
XEDIT, and DEBUG subcommands. (The VM/SP System Product Editor is 
invoked by the CMS XEDIT command.) 


"Section 18. Using the HELP Facility" describes the HELP Facility in 
detail. 


"Section 19. How the HELP Facility Works" describes the workings of the 
HELP Facility. 


"Section 20. Tailoring the HELP Facility" describes ways in which you 
can tailor the HELP facility to your needs. 


"Section 21. HELP File Naming Conventions" describes the naming 
conventions for HELP facility files. 


"Section 22. Creating HELP Files" describes the technigues that the 
HELP facility provides for creating user HELP description files. 
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Section 18. Using the HELP Facility 


The HELP facility uses the System Product Editor to display HELP files. 
The HELP facility is designed for use by 3270-type video terminals in 
full-screen mode. It can also be used by line-mode terminals. 


Note: In some installations, lowercase characters are reserved for 
display of special alphabets. In such installations, HELP files should 
be displayed in uppercase representation only. For details, see the 
VN/SP Planning and System Generation Guide. 


The documentation presented by the HELP facility is the same as given 
in the VM/SP publications. HELP displays the message text, explanation, 
system action and user action for messages. For commands, HELP will 
display the description, format, and parameters, or optionally any of 
these. HELP displays the format and description for EXEC statement. 


HELP allows you to issue CP or CMS command directly from _ the 
displayed HELP file. Thus, you may issue a command on the command line 
while viewing the HELP file for that command. The specified command 
will remain in the command line until you press Enter, even if you 
scroll the screen. This feature assists you in remembering what you 
must specify and how you must specify it. 


The HELP facility uses format words similar to those used by the IBM 
text processor SCRIPT/VS, to build and display files and menus. You 
must use these format words if you build or alter HELP files. The HELP 


format words are described in the section "HELP File Creation" which 
follows: 


SCRIPT/VS would help you if you wanted to print formatted copies of 
HELP files and menus. See the section "Printing HELP Files" for 
information on printing methods. 

The HELP facility consists of eight components: 

1. CP Commands 

Zs CMS Commands 

3. CP and CMS Messages 
4. EDIT Subcommands 

5. XEDIT Subconmmands 
6. DEBUG Sukcommands 
Te EXEC Statements 

8. EXEC 2 Statements 

Each of these components (except CP and CMS messages) has a menu that 
lists all the HELP files available for that component. You may call a 


HELP file directly or you may call a menu and then select the HELP file 
from the menu. 


If you wish to take advantage of the flexibility of the HELP Facility 
to tailor the HELP files to fit your own needs, you should also read 
"Section 19. How the HELP Facility Works" and "Section 20. Tailoring 
the HELP Facility". 
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Issuing the Help Command 


To use the HELP facility, issue the CMS HELP command. The HELP facility 
allows you to display a menu of the components for which HELP files are 
available, a menu of the HELP files available for a particular 
component, and the actual HELP files. HELP files contain descriptions, 
formats, and parameters of CMS and CP commands, EDIT, XEDIT, and DEBUG 
subcommands, and EXEC and EXEC 2 control statements, and descriptions of 
CMS and CP messages. The format of the HELP command is: 


Help Help 

message 

MENU 

component MENU 
Fr 1 
{component | 
[CMS | 
L J 


{name [ (option[) ]]} 


= __ = a aw ee oe 
a ee 


HELP displays information on how to use the CMS HELP facility. 
HELP HELP displays a description of the function of the HELP 
command, its syntax, keywords, operands, and options. 


message is the 7-character message id you specify to display the HELP 
file for a message. Specify the message id in the form 
xxxnnnt, where: 


xxx indicates the component (for example, DMS for CMS 
messages, DMNK for CP messages) 


nnn is the message number 
t is the message type 


Note that you must specify the 7-character message id, not the 
10-character id that also identifies the issuing module. For 
example, specify DMS250S rather than DMSHLP250S for 
information on that message. 


MENU displays a list of component menus available. The component 
menus list the commands, subcommands or EXEC control 
statements for which HELP files are available. MENU is the 
default if no parameters are specified. 


component 


is the name of the component you want information about. The 
HELP facility has the following components: 
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Component Description 


CaS Conversational Monitor System commands 
CP Control Program commands 

DEBUG CMS DEBUG subcommands 

EDIT CMS EDIT subconmands 

EXEC CHS EXEC statements 

EXEC 2 EXEC 2 statements 

XEDIT XEDIT subcosmands 


component MENU 
displays the menu of HELP files available for the specified 
component. There is no default component when you specify 
component MENU. (For example, if you want to display the menu 
of CMS commands, you must issue HELP CMS MENU.) 


| component nane |. 

i displays the HELP file for the specified command, subcogmand, 
| or statement. CMS command abbreviations are the only 
| abbreviations allowed when using HELP. If a component is not 
| specified, CMS is assumed. Thus, if you want to display the 
| HELP file for a CMS command, you need only specify: 


| HELP name 
| option is valid only for CMS and CP commands and subcommands. You 
may specify DESC, FORM, PARM, or ALL. ALL is the default. 


| The HELP command options are: 


| ALL display the specified HELP file starting at the 
| beginning. 


| DESC display the specified HELP file starting with the 
| description. 


| FORM display the specified HELP file starting with the format 
| specification. 


| PARM display the specified HELP file starting with the 
| parameter descriptions. 


| When a HELP command option is specified, the entire HELP file 


| is nade available to the user. The options effect only the 
| initial position of the HELP file display. 


| Examples: These are examples of HELP reguests issued as CMS commands. 
| Remember that you may also request HELP files directly from menus or 
| from the XEDIT environment. 
To request a HELP file for CP message DMKOO6I, issue: 
HELP DMKOO6I 
To request a menu of CP commands, issue: 
HELP CP MENU 
To request a HELP file for the XEDIT LOCATE subcommand, issue: 
HELP XEDIT LOCATE 
To request display of the HELP file for the CMS TAPE command beginning 


with the description, issue: 
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HELP CMS TAPE (DESC or HELP TAPE (DESC 


| Usage Notes 


=e ee ee eee ee eee 


1. 


2. 


360 


If you specify more than one option, only the first is checked for 
validity. 


HELP accesses the disk containing the system HELP files, if not 
already accessed (This disk is specified at system generation time 
by the system support personnel). The HELP disk is accessed using 
the first available filemode and remains accessed after HELP has 
completed processing. 


If the command or statement name begins with a special character, 
followed by alphanumeric characters (for example, EXEC statements 
SSTACK and SEND), HELP creates the filename by translating the 
special character as follows: 


is translated to QUESMARK 
is translated to EQUAL 
is translated to SLASH 
is translated to DBLQUOTE 
is translated to AMPRSAND 
is translated to ASTERISK 
- is translated to PERIOD 


2m aN. i ov 


The first character of the name of the special character replaces 
the special character in the filenane. 


Thus, the statements E&STACK and &END would have the filenames 
ASTACK and AEND. Remember that these changes only apply to the 
filenames of the statements; they do not affect the way you call 
for a HELP file display. To display the HELP files for &STACK and 
&END, you would issue HELP EXEC &STACK and HELP EXEC &END. 


Names which have more than one special character are handled 
differently. The first special character is handled as_ above. 
However, any special characters that are not the first character in 
the filename must be translated to the first character of their 


hame, even when asking for a HELP file display. (This applies to 
the special characters listed in the table above, and to _ the 
Asterisk, *, which must be translated to as. Remember that’ the 


asterisk is not valid as the first character of a filename.) 


Thus, to display the HELP files for the EXEC statements &*, &DISK*, 
and &DISK?, you would issue HELP EXEC 6&A, HELP EXEC &DISKA, and 
HELP EXEC &DISKQ, respectively. The following table reviews all 
the above changes: 


Ra CES mR a | 
| NAME | FILENAME | CALLED AS | 
[ ———- | 
1 & | AMPRSAND | & | 
| SSTACK | ASTACK | &STACK | 
{| &DISK? | ADISKQ | &DISKQ 
| &* | AA | GA 
| &$ | ag | &$ l 


| ee Se ee | 
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Menus 


Menus are alphabetical lists of all HELP files for a component. On 
terminals having both upper and lower case capability, menus’ show the 
Minimum abbreviation of a file nage you can issue in upper case 
characters with the remainder of the name in lower case characters (for 
example, ACcess). See Figure 29 for an example of a displayed menu. 
You can get a list of all the menus available to you by issuing: 


HELP or HELP MENU 
You get a menu by issuing: 
HELP component MENU. 
a particular HELP file directly from a 


at any part of the name and pressing the 
is displayed, you may return the menu by 


You can request display of 
menu by positioning the cursor 
PF1 key. After the HELP file 
pressing PF1 again. 


To position the cursor at the file name you want, use the cursor keys 
on your terminal, or use the TAB key (PF4) or type the desired file name 
and press PF5). When the cursor is positioned at the desired file name, 
press the PF1 key to display the HELP file for that name. The LOCATE 
subcommand cannot be used in the MENU files. To find names on MENU 
screens, enter the desired file name and press PF5. 
menu file indicates 


An asterisk (*) preceding a name in a displayed 


that the named file itself is a menu file. 


====> CMS 


(c) 


MENU <=== 


Copyrighted IBM 1980, 


1981, 


H EL P 


INFORMATION 


1982 (from IBM Form SC19-6209) 


<== 


A file may be selected for viewing hy placing the cursor under any character of 


the file wanted and press 
is preceded by an asterisk 


(*). 


the PF 1 key. 
If you 


A MENU file is 


indicated when a name 


are using a terminal that doesn't have 


a CURSOR or PF KEYS then you MUST TYPE in the COMPLETE HELP COMMAND with 
oa and options. For a description of the operands and options type HELP 
ELP. 

* DEBUG CONWAIT Edit GLOVALY LOAD NUCXMAP Rename STATE 
*Edit COPYfile ERASE HB LOADLIB OPTION RO svCtrace 
*FXec CP ESERV Felp LOADMod OSRUN RSERV SYNonyn 
*EXEC2 DDR EXec HO MACLib PEEK RT TAPE 
*Xedit DEBUG EXECIO HT MAKEBUF PRint RUN TAPEMAC 
ACcess DEFAULTS FETch HX MODmap PSERV SENDFile TAPPDS 
AMServV DES BUF FiLedef IDentify MOVEfile PUnch SENTRIES TELL 
Assemble DISK FILEList INclude NAMEFind Query SET TXTlib 
ASSGN DLBL FINIS LAbeldef NAMES RDR SETPRT Type 
ATTN DOSLIB FORMAT LISTDS NOTE RDRList 50 Update 
CMDCALL DOSLKED GENDIRT Listfile NUCEXT READcard SORT WAITRD 
CMSBATCH DROPBUF Gennod LISTIO NUCXDROP RECEIVE SSERV Xedit 
COMpare D” ERV GLobal LKED NUCXLOAD RELease START 

1= HELP 2= TOP 3= QUIT 7= BACKWARD 8= FORWARD 9= PF KEYS 
t= TAB S= LOCATE 6= PREV.CMD. 10= BACKWARD 1/2 11= FORWARD 1/2 12= CANCEL 


Figure 29. 


CMS Menu Display 
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The System Product Editor 


The System Product Editor is a full-screen CMS text editor. The HELP 
facility uses this editor to display HELP files. Many of the features 
of XEDIT subcommand are available for use on the displayed files. Two 
of the available features are: 


Locate - Locate a specified character string in the file or use 
PF5 to search the file. PF5 positions the cursor 
under the target string. 

Scrolling - Move the display up or down 


See the publication VM/SP System Product Editor Command and Macro 
Reference for complete explanations of these features. 


Not all features of System Product Editor are available for use on 
the displayed help files. The excluded features are: ADD, COMMAND, 
CURSOR, FILE, INPUT, MACRC, MODIFY, MSG, READ, REPLACE, SAVE, SET, SOS, 
AND STACK. These are excluded to prevent unnecessary copying of HELP 
files and to avoid any inadvertent changes to the help files. 


While these features will not work on files displayed by the HELP 
facility, all the System Product Editor features are available if you 
wish to use the XEDIT subcommand to edit the files (calling file by 
XEDIT filename filetype, not through HELP). 


When you issue an XEDIT subcommand to reposition the display of the 
file on the screen, HELP ensures that a full screen of data is displayed 
(if there is one). This is done to eliminate blank, or nearly blank, 
screens. 


Printing Help Files 


When displaying HELP files, you can get a printed copy of any screen by 
pressing the PF4 key while the screen is displayed. CMS sends a copy of 
the displayed screen to the currently spooled printer. This is true for 
all HELP files, except menus. 


Remember that all HELP files are CMS files and, as _ such, can be 
printed. If you want to print the files formatted, that is, looking as 
they do when displayed on your screen, you need SCRIPT/VS. If you have 
this product, you can change the filetype of any file to SCRIPT and then 
print it like any other SCRIPT file. Without SCRIPT/VS you can only 
print the HELP files unformatted. 


Note: Some special characters used in the HELP files may vary when 
printed, depending upon the printer used, and the printed output will be 
continuous with no page breaks. 
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Notational Conventions 


The HELP file notation used to define the command syntax for VM/SP is : 


e The use of the less than (<) and greater than (>) symbols denote 


choices, one of which must be selected. For example: 
<A> 
indicates that you must specify A. 
<A> 
<B> 
<C> 


indicates that you must specify either A, B, or C. 


e The use of the following notation (shown in the examples) 


choices, one which may be selected. For example: 


(A) 


indicates that you may specify A or you may omit the field. 


[cl 
+ + 


denotes 


indicates that you may specify A, B, or C, or that you may omit the 


field. 
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Using the PF Keys 


The PF keys have the following meanings when using the HELP facility: 


ae ee a ee ee oe ee eS ee eg ee ee ee ee ee 


|PF key|Meaning | Usage 


| 
PF 1 


PF2 
PF3 


PF4 
PF5 


PF6 


PF7 
PFS8 


PFS 


PF10 
PF11 


| 
| 
{ 
| 
| 
| 
| 
l 
| 
{ 
| 
[ 
| 
| 
i 
{ 
| 
| 
| 
l 
| 
l 
| 
| 
| 
| 
| 
| 
| 
| 
| 
| 
| 
| 
| 
| 
| 
| 
| 
| 
| 
| 
[ 
| 
| 
| 
| 
| 
| PF12 
| 

| 

| 

| 


LOCATE 


| PREV. 
|CMD. 


l 
|BACKWARD|moves the display towards the top of the file one 


FORWARD 


rg 
| 
rae 
@ 
ng 
07) 


1/2 


FORWARD 
1/2 


CANCEL 


| 
BACKWARD|moves the display towards the top of the file one-half 


lis used to access HELP files from a menu after the 
jcursor is positioned at the desired file name. 

[is used to return to a menu from a displayed HELP 

jfile. 

I 

|Moves the display to the top (front) of the HELP file. | 
| 

|Returns to the previous file displayed. (See Figure 30) 

| 


| 
[ 
lis used to tab through a menu. Pressing PF4 while a _ | 
[ 
| 


[menu is displayed causes the cursor to move to the 
|first character of the next file nane. 

[is used with HELP files other than menus. PF4 gives a| 
[hardcopy capability. Pressing PF4 while the HELP file| 
[is displayed causes a copy of the current screen to be| 
[sent to the currently spooled printer. After guitting | 
|HELP, issue CP SP PRT CLOSE to print the file. | 


| 

jis used with the XEDIT subcommand LOCATE on HELP 
[files. On the command line, enter the string you re 
[looking for. Then press PF5 to tell HELP to iecave” 
[the first occurrence of the string, and so on. HELP 
[highlights the line located. For detailed 

aces oe about the LOCATE subcommand, refer to the 
IVM/SP System Product Editor Command and 

| Macro Sere ccs: 

| 

[retrieves the last user command issued from the 
[command input area. 


|screen. If you screen is 24 lines, then the display 
lis moved up 20 lines. 


[moves the display towards the bottom of the file one 
[screen. If your screen is 24 lines, the display is 
jmoved down 20 lines. 

| 

[displays a file containing an explanation of PF key 
|meanings for displayed files. 


[a screen. If you screen is 24 lines, the display 
{moves up 10 lines. 


jmoves the display toward the bottom of the file one— 
[half a screen. If your screen is 24 lines, the display 
[moves down 10 lines. 


jexits from displayed HELP file. PF12 will quit all 

J|HELP files currently in storage. For example, if you 
|jcalled a menu, then called a HELP file from that menu, | 
[PF12 quits both the file and the menu and returns con—| 
[trol to the originating environment. (see Figure 29) | 
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PF12 - you 


| YOUR | 
| FILE | 
| 

i 

I 
| XEDIT | 
| Menu | 

[ 

| 
ras | 
| SET | 
| Menu | 
ere 

| 

I 
SS 
| 1st sub- | 
| command | 
ce ere NCR | 


Sea eye on 
| 2nd sub- | 


| command | 
| 


Step 1: xXEDIT a file. Then you 
want HELP for XEDIT subcommands. 


Step 2: Specify "HELP XEDIT MENU! 
to get the XEDIT Menu displayed. 


Step 3: Select the *SET file fron 
the XEDIT menu and the SET Menu is displayed. 


Step 4: Select a subconmand file fron 
the SET Menu and the file is displayed. 


Step 5: you specify "HELP XEDIT name to 
display the file of another subconmmand. 


Assume you have followed the sequence given above and the 
HELP file for the 2nd subcommand is being displayed. 


If you were to press: 


PF1- you would return to the last Menu file displayed 
(in this case step 3). 


PF3 - you would return to the previous file displayed 
(in this case step 4). 


would guit all HELP files called and return 


to your pre-HELP location (in this case step 1). 


Figure 30. 


Example of Using PF1, PF3, and PF12. 
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Section 19. How the HELP Facility Works 


The filename of a HELP file is the name of the command, subcommand, 
message, or statement. The HELP facility uses reserved filetypes to 
identify files as HELP files. 


HELP Facility Filetypes 


The filetype of the HELP file is HELPxxxx where xxxx is the name of the 
component the file belongs to. If the component name is shorter than 4 
characters, the filetype is shortened (for example, HELPCP is the 
filetype for CP commands). If the component name is longer than 4 
characters, only the first 4 characters are used (for example, HELPDEBU 
is the filetype for DEBUG subcommands). 


The only exception to the above rule is for EXEC 2 HELP files. Since 
EXEC and EXEC 2 have the same first four characters, CMS examines the 
fifth character to determine if the request is for EXEC or EXEC 2. 
Similarly, since filetypes are limited to 8 characters, CMS assigns the 
filetype HELPEXEC to EXEC files, andthe filetype HELPEXC2 to EXEC 2 
files. 


The reserved filetypes for HELP are: 


HELPCP -- for CP commands 
HELPCMS -- for CMS commands 
HELPDEBU -- for DEBUG subcommands 
HELPEDIT -- for EDIT subcommands 
HELPEXEC -- for EXEC statements 
HELPEXC2 -- for EXEC 2 statements 


HELPHELP -- HELP files for HELP 


HELPMENU -- for menus of HELP components 
HELPMSG -- for CMS and CP commands 
HELPXEDI --- for XEDIT subcommands 
HELPSET -- for XEDIT SET Subcommands 


HELPPREF -- for XEDIT PREFIX subcommands 
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Section 20. Tailoring the HELP Facility 


One of the most useful features of the HELP facility is its flexibility. 
You can take full advantage of the CMS file system format used in the 
HELP facility to tailor it as best suits you. 


If you have your own set of HELP files, you can do as you wish with 
them However, if you share a set of HELP files with other system users, 
you will have to get authority from the System Administrator to alter 
the HELP facility. 


HELP Files 


Since all HELP files are CMS files, you can add or delete files or 
menus, or change any existing file Or menu. There are ae few 
restrictions you must follow when tailoring HELP files; they are 
discussed in the following sections. 


Note: If you tailor your HELP files, you should retain documentation of 
the changes you've made. You can use that documentation to help you 
update your files when IBM issues update to the HELP facility files. 


One way you could do this would be to use the format control word 
",cm" indicating that what follows is a comment. (-cm HELP format 
work.) HELP will not display any lines ina HELP file that begin with 
the command .cm. Thus you could include information about any 
alterations you have made to your HELP files in the file itself. 


ADDING HELP FILES 


You can either add HELP files to existing components or create a new 
component with its own HELP files. 


If you add HELP files to an existing component, you should follow the 
formatting rules given in "Section 21. HELP File Naming Conventions" 
and "Section 22. Creating HELP Files". 


If you update a component you should update its menu also. You do 
this by calling the menu file with the System Product Editor, or any 
other text editor, and adding the new names anywhere in the list of 
names. Remember that the filenames; start in column 1, are one toa 
line, and are limited to 8 characters. 


DELETING HELP FILES 


You delete HELP files just as you delete any CMS file. Specify ERASE 
filename filetype to delete a file. If you delete a file, you should 
delete the filename from the menu for that component also. 


Section 20. Tailoring the HELP Facility 369 


ALTERING EXISTING HELP FILES 


To alter a HELP file, first call the file with a text processing editor. 
Then addor delete as you wish, making sure that you follow the 
instructions given in "Section 21. "HELP File Naming Conventions" and 
"Section 22. Creating HELP Files". 


Creating Menus 


Menus for the HELP facility have the filetype HELPMENU. The filename is 
the component name they serve (for example, EXEC2 HELPMENU is the 
filename and filetype for the EXEC 2 menu). Menus contain a list of the 
HELP files for that component. There are only a few restrictions you 
nust follow when creating menu files. You may precede the list of names 
with any amount of information for the user. Between this information 
and the list of names, you must include two lines with the following 
HELP format words: 


-sp 2 
-fo off 


Following these commands, you enter the filenames in any order, but they 
must begin in column 1 of the file, have 8 or less characters, and be 
one to a line. This list of names is sorted in ascending alphabetical 
order (in columns 1 thru 8) and is formatted for display on the screen. 
If there are not two consecutive blank lines found, then the file is 
considered preformatted and is not sorted or formatted by HELP. Any two 
consecutive blank lines indicates the end of the user information 
section and the beginning of the list of names for the HELP files for 
that component. Therefore you are limited to one extra space between 
items in the user area. 


EXAMPLE OF MENU CREATION 


Assume you want to add HELP fileS concerning your internal system 
procedures to the HELP facility. Chose the component name of SYS4 
(System 4) for these procedures. Then create the HELP files for these 
procedures, giving them a filename and filetype (HELPSYS4). Following 
the rules given in "Section 21. Help File Naming Conventions". Thus 
the procedures CLASS8 (a class identifying the type of printing desired) 
would be a CMS HELP file named 'class8 helpsys4&'. 


The menu file for this component would have the filename SYS4 and the 
filetype HELPMENUD and would be set up like below. This menu lists HELP 
files available for System 4 procedures. You may view a file by placing 
the cursor under any character of the filename and pressing the PF1 key. 


-sp 2 
-fo off 
CLASS8 
CLASS7 
CLASSO 
CLASSC 
MOUNT 
DEMOUNT 
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When you specify ‘help sys4 menut, the HELP facility will alphabetize 
and columnize the filenames and display this file. You may then work 
with this menu as you would with any other HELP menu. 


CHANGING MENUS 


If you addor delete or change filenames, you should change the 
associated menu. Call the menu file (filename is component name, 
filetype is HELPMENU) with a text editor and make the necessary changes. 
Remember that there is an eight-character limit on filenames, only one 
filename goes on a line, and you can insert filenames anywhere in the 
list. If you delete a filename, you should delete the line that the 
filename is on. 
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Section 21. HELP File Naming Conventions 


Naming Conventions 


When you extend the HELP text files provided, you must use the following 
Naming conventions for the HELP files: 


The filename for components, commands, subcommands, or EXECs must be 
the exact full name of the component, command, subcommand, or EXEC. 


The filename for messages has the form xxxnnnt where: 
XXX is the component code prefix (for example, DMS for CMS 


messages). See VWM/SP System Messages and Codes for a list of 
the component code prefixes. 


nnn is the message number. 
t is the message type code (for example, E for error messages in 
CMS). 


For example, the filename for the CMS message 

NO FILENAME SPECIFIED 
would be DMSOO1E. 
The filetype for components, commands, or EXECS is "HELPxxxx' where 
xxxx identifies the system associated with this component, command, 
or EXEC. 
For example, the filetype for a CMS command would be "HELPCMS*. 
The filetype for subcommands is ‘HELPxxxx' where xxxx identifies the 
command name associated with this subcommand; for example, DEBU for 
the DEBUG command. 
The filetype for messages is "HELPMSG’. 
The filetype for a list of all supported commands for a given 


function is 'HELPMENU!®. 


For example, the filename for the CMS message NO FILENAME SPECIFIED 


would be DMSOOTE. 


The following examples illustrate the naming conventions required to 


interface with the HELP command: 


Filename Filetype Description 

ACCESS HELPCMS A CMS command description 

EDIT HELPCMS A CMS command description 

CHANGE HELPEDIT An EDIT subcommand description 
DMS186W HELPMSG A CMS message description 

CMS HELPMENU A list of the CMS command and/or EXEC 


Rhames supported by the HELP facility 
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Section 22. Creating HELP Files 


The HELP facility enables the user to: 


Extend the command and message description files IBM provides with 
additional description files of the user's choice 


Produce a formatted terminal display by using the HELP format words 
when creating the HELP description file. 


Creating Additional HELP Files 


Users creating additional files for the HELP facility can format their 
own file or use the format words the HELP facility supports. These 
format words do the following: 


Draw boxes to enclose tables, illustrations or text 
Place comments within a file 


Indicate that certain input lines are to be included in the formatted 
output only under certain conditions 


Cause concatenation of input lines and left- and right-justification 
of output 


Indent only the next input line the specified number of spaces 
Indent a series of input lines the specified number of spaces 


Indent the specified number of spaces all but the first line ina 
series of input lines 


Insert blank lines between output lines 
Change the final output representation of any input character 


The HELP format words are summarized in Figure 31 Descriptions and 


examples of their use follow. 
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| Format Word | Operand Format | Function | Break | Default Value | 
|——_—————————— |“ )l——_—_—— |I—-—— I | 
| -BX (BOX) | V1tv2...V¥n | Draws horizontal and | Yes | Draws a | 
| | OFF | vertical lines around | | horizontal | 
| | | subsequent output text, | } line. | 
| | | in blank columns. | | | 
| | | | | I 
| .CM | Comments | Places comments in a file | No | | 
| (COMMENT) | | for future reference. | | | 
| | | | | | 
| .cs | n ON/OFF | Allows conditional | No | | 
| (CONDI- | {| inclusion of input in | | | 
| TIONAL | | the formatted output. | | | 
| SECTION) | | | J | 
| l | I | | 
| FO | ON/OFF | Causes concatenation of | Yes | On | 
| (FORMAT | | input lines, and left and | | | 
| - MODE) | | xcight justification of | | | 
| | | output. i | | 
| | | l l | 
| .IL (IWN- | ni+n|[-n | Indents only the next | Yes | O | 
| DENT LINES) | | line the specified i | | 
| | | number of spaces. | | | 
| | | | | | 
| .IN (IN- | ni+tn[-n | Specifies the number | Yes | O | 
| NENT) | | of spaces subsequent | | | 
| | | text is to be indented. | | | 
| | | i I | 
{| .OF (OFF- | n|+#n[-n | Provides a technigue | Yes | O | 
| SET) | | for indenting all but the | | \ 
| | | first line of a section. | | | 
| | | I I | 
| SP |} oo | Specifies the number of 1 Yes | 1 | 
| (SPACE) | | blank lines to be inserted | | | 
| | | before the next output line. | | | 
| | | | l | 
| .TR (TRANS-| st | Specifies the final output | No | | 
| LATE) | | representation of any input | | | 
I | | | | | 


Character. 


Figure 31. HELP Format Word Summary 


ENCLOSING TEXT (.BX FORMAT WORD) 


The HELP facility can insert vertical and horizontal lines in the 
formatted output to enclose text, illustrations, or tables. You use the 
-BX format word to specify when you want the horizontal lines to appear 
and in which columns the vertical lines should appear. 


The .BX format word is used in three steps to completely enclose 
text: 


1. The first time you issue the .BX format word, specify the columns 
in which you want the vertical lines to appear. For example: 


-bx 1 10 20 30 
results in the following output: 
-—$—$$$—$— | ——$_—— | —__—_______+ 
Note that this first occurrence of the .BX format word causes a 


horizontal line to appear between the first and last column you 
specified. 
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-fo 
- bx 
ein 
- of 


After the first issuance of .BX, begin entering the text that is to 
be enclosed. As HELP formats these lines, vertical lines are 
placed in the columns that you specified on .BX. However, if a 
column already has a data character in it, it is not overlaid with 
the vertical line. Note that whenever you want just a horizontal 
line to appear (for example, to separate lines in a table), enter 


the .~BX format work without operands. For example: 
- bx 
results in the following output: 


When you have finished entering the text that is to be enclosed, 


issue: 


-bx off 


to cause another horizontal line to appear and to prevent any more 


vertical lines from appearing. This output is: 


+--- > | =< === <= { ecrece--— ~+ 


The following example illustrates this technique of enclosing text. 


off 

1 10 50 
2 

8 


Item 1 Put Item1 text here. 


The 
bx 
-of 
Ite 
- DX 


= 


tin 


-bx 
-Sp 
- bx 
-Ssp 
bX 
-Sp 
- bx 
-Sp 
bx 
-Sp 
- bx 


second line can be written here. 
8 
m 2 Then put Item2 text here. 
off 


When these input lines are processed, the result is: 
| 

ten1 |Put Item1 text here. | 
|The second line can be written here. | 


| , 
tem2 |Then put Item2 text here. l 
------ | ------------ - -- - - - - - - - - - - - - -- -- - -- --- -- + 


This example shows how you can change the vertical structure several 


es in succession. The control words: 
10 20 
5 25 
10 20 
5 25 
10 20 


off 
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result in: 


+—--------- + 
l | 
+—------------------ + 
| l 
+—--—----------------- + 
| ; 
+------------------- + 
| | 
$—--------~---------- 4 
[ l 
+--------- + 


PLACING COMMENTS IN HELP FILES (.CM FORMAT WORD) 


In addition to text and format words, HELP files can contain comments. 
Comments are useful for: 


e Tracking files. You can include comments that give your name, the 
date and reason you created a file, anda future date at which the 
file may be erased. 


e Documenting formats. If you use a special format in a HELP file that 
may be accessed by other people, you may want to place notes within 
the file explaining how to update the file. 


e Place-holders. If a file is incomplete, you may want to put comments 
in the file where information should be added later. 


You can place comments in a HELP file with the .CM format word: 


-cm Created 12/21/75 
-cn Updated 3/3/76 


HELP ignores all .CM format words when processing. 


CONDITIONAL DISPLAY OF TEXT (.CS FORMAT WORD) 


You can indicate to HELP that certain sections of the file are to be 
displayed first if the appropriate HELP command options are specified. 
These options are PARM, FORM, DESC, and ALL. (See VM/SP CMS Command and 
Macro Reference for information on the use of these options.) 


In order for HELP command processing to display the appropriate 
information, you must use the .CS format word in the following manner: 


-cs 1 on 

(text for DESC option) 
-cs 1 off 
-cS 2 on 

(text for FORM option) 
-cs 2 off 
-cs 3 on 

(text for PARM option) 
-cs 3 off 
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USE OF FORMAT MODE (.FO FORMAT WORD) 


Format-mode processing means that the HELP facility displays the output 
lines without breaks, unless specifically requested, and 
right-justified. You may not want this type of formatting in all cases; 
you may want certain output to appear exactly as it appears in the HELP 
file. For this, use the .FO format word to turn off format-mode 
processing as follows: 


-fo off 
When you want to resume format-mode processing, enter: 
-fo on 


Format-mode processing is the default. 


INDENTING TEXT (.-IN AND ~.IL FORMAT WORDS) 


When you are creating documents, you may want to set off paragraphs or 
portions of text by indenting them. This often improves the readability 
by emphasizing certain text. You can cause paragraphs to be indented 
using the .IN format word. For example, the lines: 


This line is not indented. 
ein 5 
This line is indented. 


result in: 


This line is not indented. 
This line is indented. 


The .IN format word causes a break so that text accumulated before 
the .IN format word is processed and displayed, then the next text is 
processed. 


The .IN format word effectively sets a new left margin for output 
text so that when you want text indented you do not have to enter blanks 
in front of the input lines (as you would for normal typing). HELP 
continues to concatenate and justify input text lines that begin to 
column 1, but displays the output indented the number of spaces you 
specify. 


Here's another example: 


These few lines of text 
are formatted 

with enough words 

ein 5 

so that you can 

see how HELP's formatting 
process 

ein +3 

continues and may 

ein -6 

even be reversed, by using a 
negative value. 
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These lines may result in: 


These few lines of 
text are formatted 
with enough words 
so that you can 
see how HELP*s 
formatting 
process 
continues and 
may 
even be reversed, 
by using a negative 
value. 


In this example, the first .IN format word shifts output to the right 
five spaces so that text begins in column 6. The second .IN format word 
requests that the current indentation increase by three spaces’ so the 
left margin is now in column 9. When you supply a negative value with 
the .IN format word, the margin is shifted to the left. 


To cancel an indentation that is in effect, you can use a negative 
value, or you can use the format word: 


ein 0 


Because 0 is the default value, you need not specify it when you want to 
restore the left margin to column 1. You can specify simply: 


ein 


When you want to indent only a single line of text (that is, the next 
output line), use the .IL format word. For example: 


This line begins in column 1. 

ein 5 

This line begins in column 6, 
which is now the left margin. 

sil =3 

This line is shifted 3 spaces 

to the left of the current nargin. 
-il 3 

This line is shifted 3 spaces to 
the right of the current margin. 


Help processes these lines as follows: 


This line begins in column 1. 
This line begins in 
column 6, which is now 
the left margin. 

This line is shifted 3 
spaces to the left of 
the current margin. 

This line is shifted 
3 spaces to the right 
of the current margin. 


Because the .IL format word causes a break in text, you may find it 
useful to indicate the beginning of a new paragraph. For example: 


eil 3 

This line begins a paragraph. 
Pe il I 

This line begins another. 
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These lines result in: 


This line begins 
a paragraph. 

This line begins 
another. 


USE OF OFFSETS (.OF FORMAT WORD) 


In HELP formatting, an offset differs from an indentation in that 
offsets do not affect the first line immediately following the format 
word; the second and subsequent input lines are indented the specified 
number of characters. This is useful, for example, when formatting 
numbered lists where text is blocked to the right of the number. 


When a .OF format word is processed, the next text line is printed at 
the current left margin and subsequent lines (until the next .OF or .IN 
format word) are offset the specified number of characters. For 
example, the lines: 


of 5 

“=== This line begins 

a 5-character offset. 

-of 5 

=== This is another line offset 
5 characters. 

ein 5 

An indent changes the left 
margin and cancels the offset. 
-of 3 

---This paragraph begins 

at the new left margin. 

of 3 

-~--Here's one more line. 


result in: 
== This line begins a 
5-character offset. 
-_—---- This is another line 
offset 5 characters. 
An indent changes 
the left margin and 
cancels the offset. 
---This paragraph 
begins at the new 
left margin. 
---Here's one more 
line. 


An offset can be canceled with the format word. 
of 0 
This format word causes a break; subsequent text is printed at the 
current left margin, that is, whatever the indention is (0, if no .IN 
format word is in effect). 
Any INDENT format word cancels a current offset and resets the left 
Margin. If you specify a positive or negative increment with the INDENT 


format word and an offset is in effect, the offset is canceled and the 
new left margin is computed from the current indent value. 
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The .IL (INDENT-LINE) format word uses the current margin (the indent 
value plus the offset value) when computing the margin for the next 
line. 


To achieve a format that has several levels of offsetting, you can 
combine the .IN and .OF format words. 


When you use blank space following the item indicator (for example, 
the number in a numbered list), HELP may addextra blanks when it 
justifies the line; if so, the first line may not be aligned with the 
remainder of the offset iten. 


SPACING BETWEEN LINES OF TEXT (.SP FORMAT WORD) 


If you do not want an input line to be concatenated with the line above 
it, you must cause a break. To cause a break in a HELP file, begin a 
line with one or more blank characters (by using the space bar on your 
terminal keyboard). When HELP reads an input line that begins with a 
blank character, the formatting process is interrupted; all of the text 
that has accumulated for the current line is displayed as is, even if 
more words would have fit on the line; the next input line begins a new 
output line. 


To create paragraphs in text, then, all you have to do is to enter 
spaces at the beginning of each line that is to begin a new paragraph. 
For example, the input lines: 


The quick brown 

fox 

came over to greet the lazy poodle. 
But the poodle was frightened 

and ran away. 


may be displayed by HELP as: 


The quick brown fox 
came over to greet the 
lazy poodle. 

But the poodle was 
frightened and ran 
away. 


If you want to place blank lines between lines of text, you can press 
the space bar at least once on a line that has no other text, then press 
the Return or Enter key. 


Instead of entering a blank line, you can use the .SP format word. 
Thus the input lines: 


The quick brown fox came over to 
greet the lazy poodle. 

-Sp 

But the poodle was frightened 
and ran away. 


are formatted as follows by HELP: 
The quick brown fox 


came over to greet the 
lazy poodle. 
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But the poodle was 
frightened and ran 
away. 


The .SP format word allows you to enter a numeric parameter 
indicating how many spaces you want to leave on the text output. For 
example: 


-sp 5 
indicates that you want to leave five lines of space in the text output. 


You can use multiple spaces when you want a heading or a title to stand 
out, for example the lines: 


A Love Story 

-sp 3 

The quick brown fox 

was eager 

to meet the pretty poodle. 


will result in: 


A Love Story 


The quick brown fox 
was eager to meet the 
pretty poodle. 


TRANSLATING OUTPUT CHARACTERS (.TR FORMAT WORD) 


After HELP has formatted an output line but before it displays that 
line, HELP may translate any of the characters in that line to a 
different character representation. You use the .TR format word to 
request that this translation be done. For example, to request that all 
blanks (x'40") in the file be displayed as question marks, enter: 

etr 40 ? 
To stop the translation of the question mark as a blank, enter: 

tr ? ? 


Note that when the .TR format word is used without operands, the 
translation of all characters is stopped. 


Section 22. Creating HELP Files 383 


384 IBM VM/SP CMS User's Guide 


Appendixes 


This publication contains the following appendixes: 
A. Summary of CMS Commands 
B. Summary of CP Commands 
C. Considerations for 3270 Display Terminal Users 


D. Sample Terminal Sessions 


Appendixes 385 


386 IBM VM/SP CMS User's Guide 


Appendix A. Summary of CMS Commands 


Figures 32 and 33 contain alphabetical lists of the CMS commands and the 
functions performed by each. Figure 31 lists those commands’ that are 
available for general use; Figure 32 lists the commands’ used by systen 
programmers and system support personnel who are responsible for 
generating, maintaining, and updating VWM/SP. Unless otherwise noted, 
CMS commands are described in VM¥/SP CMS Command and Macro Reference. 


Code Meaning 
DOS PP Indicates that this command invokes a DOS Program Product, 


available from IBM for a license fee. 


EREP Indicates that this command is described in VM/SP OLTSEP and 
ERROR Recording Guide. Further details on the operands used 
by this command are contained in OS/VS Environmental Recording 


Editing and Printing (EREP) Progran. 


IOCP UG indicates that this command is described in the VM/SP and 


Stand-Alone Versions: Input/Output Configuration Program 
User's Guide and Reference. 


IPcs Indicates that this command isa part of the Interactive 
Problem Control System (IPCS) and is described in VM/370 IPCS 
User's Guide. 


Op Gd Indicates that this command is described in the VM/SP 
Operator's Guide. 


OS PP Indicates that this command invokes an OS program product, 
available from IBM for a license fee. 


SCRIPT Indicates that this command invokes a text processor that is 
an IBM Installed User Program, available from IBM for a 
license fee. 


SPG Indicates that this command is described in the VM/SP System 
Programmer's Guide. 
SYSGEN Indicates that this command is described in the VM/SP Planning 


and System Generation Guide. 


In addition to the commands listed in Figure 32 and 33, there are 
seven commands called Immediate commands that are handled ina different 
Manner from the others. They may be entered while another command is 
executing by pressing the Attention key (or its equivalent) and are 
executed immediately. The Immediate commands are: 


HB - Halt batch execution 
HO - Halt tracing 

HT - Halt typing 

Halt execution 

RO - Resume tracing 

RT - Resume typing 

SO - Suspend tracing 
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| Command 


| 
[ACCESS 


AMSERV 


ASSEMBLE 


ASSGN 


CMDCALL 


CMSBATCH 


QO 
o) 
to 
Oo 
t 


COMPARE 


CONVERT 


COPYFILE 


oO 
td 
to 
(=| 
Q 


DEFAULTS 


oO 
H 
UW) 
| 


DLBL 


DOSLIB 


DOSLKED 


ee 
Figure 32. 


Code 


OS PP 


OS PP 


EREP 


VSE PP 


; Usage 


[Identify direct access space to a CMS virtual 
|machine, create extensicns and relate the disk 
|space to a logical directory. 

| 

[Invoke access method services utility functions to 
|create, alter, list, copy, delete, import, or 
jJexport VSAM catalogs and data sets. 

l 

|Assemble assembler language source code. 

[ 

[Assign or unassign a CMS/DOS system or programmer 
[logical unit for a virtual I/O device. 

[ 

|Converts EXEC 2 extended plist function calls to 
[CMS extended plist command calls. 

| 

{Invoke the CMS batch facility. 

[ 

|Compile OS ANS Version 4 or OS/VS COBOL source 

| code. 

{ 

|Compare records in CMS disk files. 

I 

|Convert free form FORTRAN statements to fixed forn. 
[ 

|Copy CMS disk files according to specifications. 

| 

[Enter CP commands from the CMS environment. 


| 
|Format and edit system error records for output. 


[Perform backup, restore, and copy operations for 
jdisks. 


| 
{Enter DEBUG subcommand environment. 


| 

[Set or display default options for the commands: 

| FILELIST, NOTE, RDRLIST, RECEIVE, PEEK and SENDFILE 
| 

{Perform disk—to—-card and card—to—disk operations 
|for CMS files. 

| 

|Define a VSE filename or VSAM ddname and relate 
[that name to a disk file. 

{ 

|Delete, compact, or list information about the 
[phases of a CMS/DOS phase library. 

| 

jLink—-edit CMS text decks or object modules from a 
I VSE relocatable library and place them in 
J|executable form in a CMS/DOS phase library. 

I 

| Compile DOS PL/I source code under CMS/DOS. 

| 

|Eliminate a program stack buffer. 

| 

{Display information contained in the VSE core 
Jimage, relocatable, source, procedure, and 


jtransient directories. 
ea a a ll 
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| Command 


I 
[EDIT 


ta 
Pi 
ta 
Q 


EXECIO 


| FCOBOL 


l 
| FETCH 


I 
| FILEDEF 
| 


{ 
| FILELIST 


I 

| 
[FINIS 
| 

| FORMAT 


| 
| FORTGI 


| 
| FORTHX 
| 


| 
|GENDIRT 
| 

| GENMOD 


GLOBAL 


| IDENTIFY 


[ 
I 
| INCLUDE 


| Code 


VSE PP 


OS PP 


OS PP 


OS PP 


[ Usage 

[Invoke the VM/SP System Product editor in CMS 
jeditor (EDIT) compatibility mode to create or 
[modify a disk file. 

[ 

[Delete CMS disk files. 


l 

|Display, punch or print an edited (compressed) 
[macro from a VSE source statement library 

| (E sublibrary). 

| 

| Execute special procedures made up of frequently 
Jused sequences of commands. 

I 

|Do I/0 operations between a device and the progran 
[stack. 

| 

[Compile DOS/VS COBOL source code under CMS/DOS. 

| 

[Fetch a CMS/DOS or VSE executable phase. 

l 

|Define an OS ddname and relate that ddname to any 
|device supported by CMS. 

| 

JList information about CMS disk files, with the 
Jability to edit and issue commands from the list. 
l 

|Close an open file. 

l 

|Prepare disks in CMS fixed block format. 


| 

|Compile FORTRAN source code uSing the G1 compiler. 
|Compile FORTRAN source code using the H—extended 
|compiler. 


[Fill in auxiliary module directories. 

| 

|Generate nonrelocatable CMS files (MODULE files). 

l 

|Identify specific CMS libraries to be searched for 
|macros, copy files, missing subroutines, LOADLIB 
|modules, or DOS executable phases. 

l 

|Set, maintain, 
| variables. 


and retrieve a collection of naned 


|Compile FORTRAN source code and execute the progran 


Jusing the FORTRAN Code and Go compiler. 

| 

| Display information about CP, CMS, or user 
jcommands, EDIT, XEDIT, or DEBUG subcommands, EXEC 
Jand EXEC2 control statements, and descriptions of 
[CMS and CP messages. 

| 

| Display or stack userid, nodeid, rscsid, date, 
[time, time zone, and day of the week. 

| 

|Bring additional TEXT files into storage and 
Jestablish linkages. 
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| Command 


| 
| IOCP 


| 

| LABELDEF 
| 

| 

| 

{LISTDS 

| 

| 


| LISTFILE 
| 

| LISTIO 

| 

| 

| LKED 

I 


I 
| LOAD 


l 
| LOADLIB 
| 
| LOADMOD 


I 
| MACLIB 


| 
| MAKEBUF 


[ 
| MODMAP 


[ 
|MOVEFILE 
| 


| 
| NAMEFIND 


[ 
| NAMES 


4} 
© 
| 
is) 


NUCXDROP 


NUCXLOAD 


NUCXMAP 


OPTION 


oO 
1S?) 
=o) 
a 
= 


PEEK 


A) 
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| Code 


| 
| 
| 
| 
| 
| 
| 
| 
| 
| 
| 
| 
| 
| 
I 
| 
| 
| 
| 
| 
| 
| 
| 
| 
| 
| 
| 
| 
| 
| 
{ 
| 
| 
| 
| 
| 
| 
| 
| 
| 
| 
| 
| 
| 
| 
| 
| 
| 
| 
| 
| 
| 
| 
l 
| 
| 
}OS PP 
| 


| Usage 


IOCP UG|Invoke the Input/Output Configuration Program 


I 
[Specify standard HDR1 and EOF1 tape label descrip— 


jtion information for CMS, CMS/DOS, and OS 
[simulation. 

I 

[List information about data sets and space 
Jallocation on OS, DOS, and VSAM disks. 

| 

[List information about CMS disk files. 

| 

[Display information concerning CMS/DOS system and 
[programmer logical units. 

[ 

[Link edit a CMS TEXT file or OS object module into 
Ja CMS LOADLIB. 

[ 

[Bring TEXT files into storage for execution. 
| 

[Maintain CMS LOADLIB libraries. 

I 

[Bring a single MODULE file into storage. 

l 

[Create or modify CMS macro libraries. 

l 

|Create a new program stack buffer. 

| 

[Display the load map of a MODULE file. 

| 

|Move data from one device to another device of the 
|same or a different type. 

| 

|Display/stack information from a NAMES file. 
| (default ‘userid NAMES"). 


[Display a menu to create, display or modify entries 


jin a ‘userid NAMES! file. (The menu is available 
[only on display terminals.) 

[ 

[Prepare a 'note' for one or more computer users, 
[to be sent via the SENDFILE command. 

| 

| Delete specified nucleus extensions. 


[Load a nucleus extension. 


| 

[Identify existing nucleus extensions. 

{ 

{Change the DOS/VS COBOL compiler (FCOBOL) options 
jthat are in effect for the current terminal 

| session. 

; 

JLoad, relocate, and execute a load module from a 
[CMS LOALCLIB or OS module library. 


| Display a file that is in your virtual reader with— 


Jout reading it onto disk. 

[ 

{Compile and execute PL/I source code uSing the 
| PL/I Checkout Compiler. 
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Se ee 
{Command | Code [ Usage 


[ 
| PLICR [OS PP |Execute the PL/I object code generated by the OS 
| | | PL/I Checkout Compiler. 

[ l [ 

{| PLIOPT {OS PP |Compile PL/I source code using the OS PL/I 

| J}Optinizing Compiler. 

[ [ 


I 

[ 

i 

[ 

l 

| 

[ ; 

[ [ 

| PRINT i {Spool a specified CMS file to the virtual printer. | 
; | | | 
[| PSERV [ |Copy a procedure from the VSE procedure library | 
[ | Jonto a CMS disk, display the procedure at the I 
| | [terminal, or spool the procedure to the virtual | 
| [ {punch or printer. | 
[ | | I 
| PUNCH | [Spool a copy of a CMS file to the virtual punch. | 
| | ; ( 
| QUERY [ |Request information about a CMS virtual machine. | 
l [ | I 
| RDR | [Generate a return code and either display or stack | 
| | |a message that identifies the characteristics of | 
| | |the next file in your virtual reader. | 
| [ | l 
|RDRLIST [ [Display information about files in your virtual i 
| [ |reader with the ability to issue commands from the | 
l | jlist. 
| | | ( 
| RECEIVE | [Read onto disk a file or note that is in your | 
| | |virtual reader. { 
| | [ j 
|READCARD | {Read data from spooled card input device. [ 
; | l | 
|RELEASE | [Make a disk and its directory inaccessible to a CMS| 
| [ |virtual machine. { 
I | i | 
| RENAME | [Change the name of a CMS file or files. | 
I [ [ l 
|RSERV ] {Copy a VSE relocatable module onto a CMS disk, | 
| | [display it at the terminal, or spool a copy to [ 
| | {the virtual punch or printer. | 
| [ I [ 
[RUN | |Initiate series of functions to be performed ona | 
| | |source, MODULE, TEXT, or EXEC file. | 
[ { | l 
| SCRIPT [SCRIPT |Format and print documents according to embedded \ 
| | |SCRIPT control words in the document file. | 
i | | 
|SENDFILE | |Send files or notes to one or more computer users, | 
| | Jattached locally or remotely, by issuing the | 
| | |command or by using a menu. (display terminal only) | 
| [ l [ 
{SENTRIES | | Determine the number of lines currently in the | 
| | | program stack. | 
[ | | | 
|SET [ |Establish, set, or reset CMS virtual machine | 
| | | characteristics. | 
| ( | [ 
| SETPRT [ {Load a virtual 3800 printer. | 
I ; [ [ 
|SORT | {Arrange a specified file in ascending order | 
[ [ Jaccording to sort fields in the data records. | 
a ee ee a Ne ee | 
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| TAPE 
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| TAPEMAC 
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| TAPPDS 


TELL 


| TESTCOB 
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l 
| VSAPL 


| 
| VSBASIC 


| 
| VSBUTIL 


| 
| XEDIT 
| 


OS 


OS 
OS 
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| 
| 
| 
| 
[ 
| 
| 
| 
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| 
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| 
| 
| 
| 
| 
| 
| 
| 
| 
| 
| 
| 
| 
| 
| 
| 
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| 
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| 
| 
| 
| 
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PP 


PP 


PP 


PP 


I Usage 


[Copy a VSE source statement book onto a CMS 
|disk, display it at the terminal, or spool a copy 
Jto the virtual punch or printer. 

l 

[Begin execution of programs previously loaded (0S 
Jand CMS) or fetched (CMS/DOS). 

I 

|Verify the existence of a CMS disk file. 

| 

[Verify a file on a read/write CMS disk. 

; 


|Record information about supervisor calls. 


|Invoke a table containing synonyms you have created 


|for CMS and user—written commands. 

; 

|Perform tape—to—disk and disk—to—tape operations 
[for CMS files, position tapes, and display or 
|write VOL1 labels. 

| 

[Create CMS MACLIB libraries directly from an 

| TIEHMOVE-created partitioned data set on tape. 

; 

[Load OS partitioned data set (PDS) files or card 
[image files from tape to disk. 

| 

|Send a message to one or more computer users who 
Jace logged on to your computer or to one attached 
[to yours via RSCS. 

| 

| Invoke the OS COBOL Interactive Debug Progran. 

| 

[Invoke the FORTRAN Interactive Debug Progran. 

l 

[Generate and modify text libraries. 

[ 

|Display all or part of a CMS file at the terninal. 
l 

[Make changes in a program source file as defined 
[by control cards in a control file. 

| 

jInvoke VS APL interface in CMS. 

| 

|Compile and execute VS BASIC programs under CMS. 
l 

[Convert BASIC 1.2 data files to VS BASIC format. 
| 


JInvoke the VM/SP System Product Editor to create or 


[modify a disk file. 
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{Command 
; 
{ASM3705 
( 
| ASMGEND 


I 
|CMSGEND 
| 


{ 

| CMSXGEN 
| 

| CPEREP 
I 

| DIRECT 


[ 
| DOSGEN 


l 
| DUMPSCAN 


| 
[GEN3705 
! 


I 
|GENERATE 
| 


| 
| LKED 


; 
|NCPDUMP 
[ 


| 
| PRB 


; 
| PROB 


| 

[PROP 

l 

| SAMGEN 


I 
|SAVENCP 
I 


SETKEY 


STAT 
VMFBLD 


VMFDOS 


| 
| 
| 
| 
| 
| 
| 
| 
| VNFDUMP 
| 

l 

|VMFLOAD 


! 
| VSAMGEN 


| 
| ZAP 
| 


| Code 
| SYSGEN 
[ 

| SYSGEN 


| 
|SYSGEN 
| 


| SYSGEN 


| SYSGEN 


SYSGEN 


SYSGEN 


SPG 


un 
4") 
rp) 


IPCS 


SYSGEN 


SYSGEN 


|Op Gd, 
J] IPCS 

| SYSGEN 
|SYSGEN 


|Op Gd, 


SYSGEN, |Read 370x centrol program load into virtual 


| Usage 
| Assemble 370x source code. 


|Regenerate the VM/SP assembler command modules. 
| 


[Generate a new CMS disk—-resident nodule fron 
updated TEXT files. 
Generate the CMSSEG discontiguous saved segment. 
Formats and edits system error records for output. 
Set up VM/SP directory entries. 
Load and save the CMSDOS shared segment. 
Provide interactive analysis of CP abend dumps. 
Generate an EXEC file that assembles and link—edits 
the 370x control progran. 
a new standalone copy of a service progran. 


Link—edit the 370x control progran. 


Process CP spool reader files created by 370x 
dumping operations. 


Update IPCS problem status. 
Enter a problem report in IPCS. 
Provide Programmable Operator Capability. 


l 
| 
I 
l 
| 
| 
| 
I 
| 
I 
| 
| 
i 
| 
[Update VM/SP or the VM/SP directory, or generate 
| 
A 
| 
| 
| 
l 
[ 
i 
[ 
I 
| 
{ 
i 
[Save the CMSBAM discontiguous saved segment. 
| 


{| storage and save an image on a CP—owned disk. 

[ 

[Assign storage protect keys to storage assigned to 
| named systems. 


l 
[Display the status of reported system problems. 


I 
[Generate and/or update VM/SP using the PLC tape. 


| 
{Create CMS files for DOS modules from DOS library 
| distribution tape or SYSIN tape. 


Format and print system abend dumps; under IPCS, 
create a problem report. 


Generate a new CP, CMS or RSCS module. 
Load and save the CMSVSAM and CMSAMS segments. 


Modify or dump LOADLIB, TXTLIB, or MODULE files. 


Figure 33. 
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Figure 34 describes the CP command privilege classes. 


Bl 


C1 


D1 


Bl 


Fil 


G2 


Any? 


H 


User and Function 


Primary System Operator: The class A user controls the 

VM/SP system. Class A is assigned to the user at the VM/SP 
system console during IPL. The primary system operator is 
responsible for the availability of the VM/SP system and its 
communication lines and resources. In addition, the class A 
user controls system accounting, broadcast messages, virtual 
machine performance options and other command operands that 
affect the overall performance of VM/SP. 


Note: The class A system operator who is automatically logged 


on during CP initialization is designated as the primary 
system operator. 


System Resource Qperator: The class B user controls all the 
real resources of the VM/SP system, except those controlled 
by the primary system operator and spooling operator. 


System Programmer: The class C user updates certain 
functions of the VM/SP systen. 


Spooling Operator: The class D user controls spool data 
files and specific functions of the system's unit record 
equipment. 


System Analyst: The class E user examines and saves certain 
data in the VM/SP storage area. 


Service Representative: The class F user obtains, and 
examines, in detail, certain data about input and output 
devices connected to the VM/SP systen. 


General User: The class G user controls functions associated 
with the execution of his virtual machine. 


The Any classification is given to certain CP commands that 
are available to any user. These are primarily for the 
purpose of gaining and relinguishing access to the YM/SP 
systen. 


Reserved for IBM use. 


1Described in the VM/SP Operator's Guide. 
2Described in the VM/SP CP Command Reference for General Users. 
_ ee a ae 


Figure 34. 


CP Privilege Class Descriptions 


L. 
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Figure 


35 contains 


an alphabetical list of the CP commands, the 
privilege classes which may execute the command, and a brief statement 
about the use of each ccmmand. 


Se ee ee 
Privilege | 


Command 


ACNT 


ADSTOP 


ATTACH 


ATTN 


AUTOLOG 


BACKSPAC 


BEGIN 


CHANGE 


CLOSE 


COUPLE 


CP 


CPTRAP 


| 
[ 
| 
| 
| 
| 
| 
| 
| 
| 
| 
| 
| 
| 
| 
| 
| 
| 
| 
| 
| 
| 
| 
| 
| 
| 
| 
| 
| 
| 
| 
| 
| 
| 
| 
| 
| 
| 
| 
| 
| 
| 
| 
| 
| 
| 


Class 
any 


any 


td to to 


any 


Cc 


| Usage 

I 

j|Annotate the console sheet. 

| 

[Execute a CP command while remaining in the 
virtual machine environment. 


Create accounting records for logged on users 
and reset accounting data, and close the 
spool file that is accumulating accounting 
records. 


l 
| 
| 
[ 
| 
[ 
[ 
[Halt execution at a specific virtual machine 
| instruction address. 

| 

[Attach a real device to a virtual machine. 

| Attach a DASD for CP control. 

| Dedicate all devices on a particular channel 
1 to a virtual machine. 


Make an attention interruption pending for the 
virtual machine console. 


Automatically log on a virtual machine and 
have it operate in disconnect mode. 


Restart or reposition the output of a unit 
record spooling device. 


Continue or resume execution of the virtual 
machine at either a specific storage location 
or at the address in the current PSW. 


Alter one or more attributes of a closed spool 
file. 


oe ogee eee ee eee eee Ce ee ee ee eee eee 


|Terminate spooling operations on a virtual card 
| ceader, punch, printer, or console. 

[ 

{Connect channel-to-channel adapters. 

[ 

[Execute a CP command while remaining in the CMS 
| virtual machine environment. 


|Create a file of selected trace table, CP inter-— 


| face, and virtual machine interface entries 
| ‘for problem determination. 


eee 
Figure 35. 
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I | Privilege | 
{| Command | Class | Usage | 
[ | | | 
| DCP | C,E |Display real storage at terminal. | 
| | | 
| DEFINE | G |Reconfigure your virtual machine. | 
| | B |Redefine the usage of SYSVIRT and VIRTUAL 3330V | 
[ . | | devices. | 
| | | | 
| DETACH | B |Disconnect a real device from a virtual machine. | 
| | B |Detach a DASD volume from CP. | 
I {| B |Detach a channel from a specific user. [ 
{ [| G [Detach a virtual device from a virtual machine. | 
| | G |Detach a channel from your virtual machine. | 
I [ [ 
| DIAL | any |Connect a terminal or display device to the | 
[ | | virtual machine's virtual communication line. | 
| [ | | 
| DISABLE | A,3B [Disable 2701/2702/2703, 370X in EP node, | 
| [ | and 3270 local communication lines. [ 
l [ [ | 
| DISCONN | any [Disconnect your terminal from your virtual | 
| \ | machine. r 
| i | | 
| DISPLAY | G |Display virtual storage on your terminal. | 
l [ | | 
| DMCP | C,E |Dump the specified real storage location on your| 
| | | virtual printer. | 
| I | ( 
| DRAIN {| D |Halt operations of specified spool devices upon | 
| [ | completion of current operation. [ 
I l | | 
| DUMP | G | Print the following on the virtual printer: [ 
| | | virtual PSW, general registers, floating-point| 
| | | registers, storage keys, and contents of | 
| | | specified virtual storage locations. | 
| I | [ 
| ECHO | G |Test terminal hardware by redisplaying data | 
| | | entered at the terminal. | 
| ; l { 
{ ENABLE | A,B [Enable communication lines. | 
| | | { 
| EXTERNAL | G |Simulate an external interruption for a virtual | 
| | | machine and return control to that machine. | 
| | | 
| FLUSH | D [Cancel the current file being printed or punched| 
[ | | on a specific real unit record device. | 
[ | | | 
| FORCE | A |Cause logoff of a specific user. | 
[ | | | 
| FREE | D {Remove spool HOLD status. | 


a wr sa tl ee ee ee Fe 
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Command 


HALT 


HOLD 
INDICATE 
IPL 


LINK 


LOADBUF 


LOADVFCB 


LOCATE 


LOCK 


LOGOFF 
LOGON 
MESSAGE 


MIGRATE 
MONITOR 


MSGNOH 
NETWORK 


| 
| 
| 
| 
| 
| 
| 
| 
| 
| 
| 
| 
| 
| 
| 
I 
I 
| 
| 
| 
| 
I 
| 
I 
| 
| 
| 
| 
| 
| 
| 
I 
| 
| 
| 
| 
| 
| 
| 
| 
| 
| 
| 
| NOTREADY 
| 


Class 


A 


G 


Privilege | 


| Usage 


Terminate the active channel program on 
specified real device. 


Defer real spooled output of a particular uSer. 
Indicate resource utilization and contention. 
Simulate IPL for a virtual machine. 


Provide access to a specific DASD by a 
virtual machine. 


Load real UCS/UCSB or FCB printer buffers. 


Load virtual forms control buffer for a virtual 
3203 or 3211 printer. 


Find CP control blocks. 


Bring virtual pages into real storage and lock 
them; thus, excluding them from future paging. 


isable access to CP. 


g YD 


rovide access to CP. 


|Transwit messages to other users. 


[Allows the operator to migrate pages either for 
[the entire system or just one user. 

| 

|Trace events of the real machine and record 
system performance data. 


Send a specified message, without the standard 
message header, from one virtual machine to 
another. 


Load, dump, and control the operation of the 
370X control program. Control the operation 
of 3270 remote devices. 


Simulate "not ready" for a device to a virtual 


[ 
l 
[ 
| 
| 
[ 
I 
I 
I 
| 
| machine. 


Mn i ee J 


Figure 35. 
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| |Privilege| [ 
| Command | Class | Usage | 
f I l 
| ORDER | D,G {Rearrange closed spool files in a specific { 
| | order. | 
I [ | { 
| PURGE | D,G |Remove closed spool file from systen. { 
; | | i 
| QUERY | A,B,C,D, |Request information about machine configuration | 
| | E,F,G | and system status. | 
; I | I 
| OVA | A |Reguest the transition from VM/SP to the V=R | 
| | | virtual machine running in native mode. | 
[ | | | 
| READY | G {Simulate device end interruption for a virtual | 
| | | device. | 
; | l [ 
| REPEAT {| D |Repeat (a specified number of times) printing or| 
| | | punching of a specific real spool output file. | 
[ [ | ; 
| REQUEST | G |Make an attention interruption pending for the | 
| { | virtual machine console. [ 
| | [ 
| RESET | G |Clear and reset all pending interruptions for a | 
| | | specified virtual device and reset all error | 
[ [ | conditions. | 
{ | | | 
| REWIND | G {Rewind (to load point) a tape and ready a tape | 
| | | unit. | 
| | l | 
| SAVESYS | E |Save virtual machine storage contents, registers| 
| | | and PSW. | 
| | [ | 
| SCREEN | G {Control color and extended highlight attributes | 
| | | of the screen. | 
| SET | A,B,E,F, |Operator—establish system parameters. | 
| | G | User—control various functions within the [ 
| { | virtual machine. | 
[ | | | 
| SHUTDOWN | A {Terminate all VM/SP functions and checkpoint CP | 
| | | system for warm start. | 
f | [ ; | 
| SLEEP | any |Place virtual machine in dormant state. | 
| | | [ 
| SMSG | G |Send special message to appropriate virtual ; 
| ie | machine. 
[ | | | 
| SPACE | D [Force single spacing on printer. | 
| | l l 
| SPMODE | A [Establish or reset the single processor node | 
| | | environment. | 


Figure 35. CP Command Summary (Part 4 of 5) 


Appendix B. Summary of CP Commands 399 


eg fa ea ee ee ye tee mea ee Fen APO Se a gee ge ep pe eee eee ee ee 


a = eee eee ee ee eee oe ees ees eee eee ee eee eae ee ee ieee oe eee ioe ee eee ees ees es eee es ee aio eee ee oe 


Command 


SPOOL 


SPTAPE 


START 


STCP 


STORE 


SYSTEM 


TAG 


TERMINAL 


TRACE 


TRANSFER 


UNLOCK 
VARY 


VMDUMP 


WARNING 


Privilege| 
Class 


G 


[ Usage 


Alter spooling control options; direct a file to 
another virtual machine or to a renote 
location via the RSCS virtual machine. 


Dump output spool files on tape or load output 
spool files from tape. 


Start spooling device after draining or changing 
output classes. 


Change the contents of real storage. 


Alter specified virtual storage locations and 
registers. 


Simulate RESET, CLEAR STORAGE, and RESTART 
buttons on a real system console. 


| 

[ 

| 
| I 
| [ 
; i 
| l 
[ ; 
| h 
| l 
| | 
( [ 
| [ 
l I 
| i 
[ [ 
[ [ 
l [ 
4 | 
( { 
| [ 
[Specify variable information to be associated | 
| with a spool file or output unit record | 
| device. | 
[Interrogate the current TAG text setting of a [ 
| given spool file or output unit record device. | 
l | 
|Define or redefine the input and attention | 
f ( 
| l 
| [ 
| [ 
l | 
| l 
| | 
| l 
| [ 
[ [ 
| [ 
; l 
[ | 
| i 
| ( 
| | 
| [ 
[ ( 


handling characteristics of your virtual 
console. 


Trace specified virtual machine activity at your 
terminal, spooled printer, or both. 


Transfer input files to or reclaim input files 
from a specified user's virtual card reader. 


Unlock previously locked page frames. 
Mark a device unavailable or available. 


Dump virtual machine when issued with the 
VM/IPCS Extension program product. 


Transmit a high priority message to a specified 
user or to all users. 


ee ee ee a ee EN ee | 
Figure 35. CP Command Summary (Part 5 of 5) 
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Appendix C. Considerations for 3270 Display Terminal 
Users 


The IBM 3270 display terminal, commonly referred to as a 3270, functions 
sonewhat differently from a typewriter-style terminal when you use it as 
a virtual machine console under VM/SP. Apart from the obvious 
difference in the way output is displayed, there are special techniques 
you can use with a 3270 that you cannot use on a 2741 or other 
typewriter terminal. This appendix describes how to use a 3270 and 
provides additional notes to supplement discussions in the first part of 
this publication. 


Entering Commands 


Since the keyboard on a 3270 is never locked during the execution of a 
command or program, you can enter successive command lines without 
waiting for the completion of the previous command. This’ stacking 
function can be combined with the other methods of stacking lines, such 
as using the logical line end symbol (#) to stack several command lines. 
If you try to enter more lines than the terminal buffer can accommodate, 
however, you receive the status message NOT ACCEPTED and you must wait 
until the buffer is cleared before you can enter the line. 


You will find, as you become accustomed to uSing a 3270, that the #CP 
function is very useful. The #CP function, remember, is a function that 
allows you to pass a command line to the control program immediately, 
bypassing any processing by the virtual machine (CMS). The #CP function 
can be used in any VM/SP environment, and you can enter it even when a 
program is executing. You do not have to interrupt a program's execution 
to enter a command line such as: 


#cp display psw 
to display the current PSW, or: 
#cp spool printer class s 


to spool your virtual printer. 


RETRIEVE Function 


One of the most common user difficulties is typing errors. The 
RETRIEVE function provides a convenient and time-saving method of 
correcting errors without retyping the entire input. You can use this 
function by defining a program function (PF) key for it, using a command 
such as: 


#CP set pf12 retrieve 


If you define a PF key for the RETRIEVE function, VM/SP remembers each 
input line entered at the terminal. When you press the PF key, VM/SP 
redisplays the latest input line in the input area, so that you can 
modify and re-enter the data. This allows you to correct errors, change 
your input, or repeatedly reissue a command. 


VM/SP actually remembers several input lines. The number of lines 
remembered depends on the length of the lines; VM/SP remembers hore 
short lines than long lines, but it can always remember at least one 
full input line. Duplicate input lines (lines that are the same as the 
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previous input) are not remembered since it is not useful to remember 
the same line twice. For security reasons, input lines that are not 
displayed at the terminal, such as passwords, are never remembered. 


When a RETRIEVE program function key is first pressed, VM/SP 
redisplays the latest input line. If a RETRIEVE key is pressed again, 
VM/SP displays the previous input line. As the key is’ pressed, VM/SP 
steps through the input lines displaying them one at a time. When VM/SP 
reaches the oldest line that it has remembered, it cycles back to the 
latest one again. When an input line is entered, VM/SP resets itself so 
that the RETRIEVE program function key starts with the latest input 
line. 


Note: For CP and CMS commands, there isa simple way to reset’ the 
RETRIEVE function to the latest input line: simply enter a_ single 
asterisk (*), which is treated as a comment by both CP and CMS. Then 
press the RETRIEVE program function key once to get the asterisk 
redisplayed, and a second time to get the previous input line 
redisplayed. 


Setting Program Function Keys 


If there are CP and CMS commands that you use frequently, you can set 
the program function (PF) keys on your terminal to execute them. Some 
examples of commands you might wish to catalog on PF keys are: 


#CP DISPLAY PSW 
#CP QUERY PRINTER ALL 
QUERY SEARCH 


To set functions keys 1, 2, and 3 to perform these command functions, 
enters 


cp set pf1 immed “#cp display psw 

cp set pf2 immed "#cp query printer all 

cp set pf3 immed guery search 
When you want to execute a #CP function with a PF key, or you want a PF 
key to execute a series of commands, you must use the logical escape 
symbol (") when you enter the SET command. For example: 


cp set pf5 immed edit test file"#bo"#input line"#file 
sets the PF5 key as: 
EDIT TEST FILE#BO#INPUT LINE#FILE 


The above examples use the IMMED operand of the SET command, which 
specifies that the function is performed as soon as you press’ the PF 
key. You can also set a key so that it is delayed; that is, the command 
or data line is placed in the user input area. Then, you must press the 
Enter key to execute the command. You may modify the line before you 
enter it. This is the default setting (DELAY) for program function keys. 
For example, you might set a key as: 


QUERY DISK x@ 
When you press this PF key, the command line is placed in the user input 
area, with the cursor positioned following the "@" logical character 
delete symbol; you can enter the mode letter of the disk you are 
querying before you press the Enter key to execute the command. If you 
enter ‘A', the resulting command as seen by CMS is "QUERY DISK A*. 


You can set all of your program function keys in your PROFILE EXEC, 
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so they are set each time you load CMS. You can change a PF key setting 
any time during a terminal session, according to your needs. If, for 
example, you discover that you are repeating several procedures a number 
of times, and the procedure does not lend itself to being written into 
an EXEC, you could use your program function keys. 


All the lines in an EXEC procedure are scanned, and all character 
strings are truncated to eight characters, so if you enter a long 
command line, insert spaces where possible: 


CP SET PF5 IMMED EDIT TEST FILE #BO# INPUT 


To change PF settings within the edit environment, give the EXEC a 
filename that begins with a dollar sign ($), so it functions as an edit 
macro. 


For more details on setting PF keys, see the VM/SP Terminal User's 
Guide. 


Controlling the Display Screen 


During a CP or CMS session (other than an EDIT session) messages and 
warnings from the system operator or other users are highlighted. This 
distinguishes these messages frcem other output and lessens’ the 
possibility of important messages being lost or ignored. 


A major feature of a 3270 display screen is the screen status area, 
which indicates, at all times that you are logged on, the current 
operating condition your virtual machine is in. Understanding the 
status conditions can help you use CMS on a 3270 more effectively. The 
screen status area indicates one of seven conditions: 


CP READ: After you log on, this is the first status message you see; it 
indicates that the terminal is waiting for a line to be read by the 
control program. You can enter only CP commands when the screen status 
area indicates a CP READ. 


VM READ: This status indicates that your terminal is waiting for a line 
to be issued to your virtual machine; you may be in the CMS environment, 
in the edit or debug environments, or you may be executing a program or 
an EXEC that has issued a read to the console. 


RUNNING: This status means that your virtual machine is operating. Once 
you have loaded CMS and are using the CMS environment, this status is 
almost continually in effect, even when you are not currently executing 
a command or program. 


You can alter the way this works by uSing the AUTOREAD function of 
the SET command. When the AUTOREAD setting is OFF, (the default for 
display terminals), your terminal displays a RUNNING status after the 
execution of each CHS command. If you want the terminal to be ina VM 
READ status following each command, issue: 


set autoread on 


The ON setting is the default for typewriter terminals, since a read on 
a typewriter terminal must be accompanied by the unlocking of the 
keyboard. 


The advantage of keeping your virtual machine ina running Status 
even when it is not actually executing a program is that it makes your 
terminal ready to receive messages. If your terminal is waiting for a 
read, either from CP or from the virtual machine, and if a user ora 
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program sends a message to your virtual console, then the message is not 
displayed until you use the Enter key to enter a command or null line. 
When your machine is in a running status, the terminal console is always 
ready to accept messages. 


If your virtual machine is in the CP environment, and you want your 
terminal to be in a running status, you can use the command: 


cp sleep : 


To return to the CP READ status, you must press the PA1 key or the Enter 
key. 


MORE...: This status indicates that your display screen is full, but 
that there is more data to be displayed. This message, in addition to 
indicating that there is more data, gives you a chance to freeze your 
screen's current display so you can continue to examine it, if 
necessary. 


When you see the screen is in a MORE... status, you can either (1) 
press the Clear, Cancel, or PA2 keys to clear the screen and_ see the 
next screen, or (2) press the Enter key to hold the screen in its 
present status. If you do not do either, then after 60 seconds, the 
screen is cleared and the next screen is displayed. 


HOLDING: This indicates that you have pressed the Enter key to freeze 
the screen. You must use the Cancel, Clear, or PA2 keys’ to erase this 
screen and go on to the next display. 


A holding status also results if you have received a message that 
appeared on this screen. When the screen becomes full, it does not 
automatically pass to the next display after 60 seconds, but waits until 
you specifically clear the screen. (This feature ensures that any 
important messages you receive are not lost.) 


NOT ACCEPTED: Indicates that you are trying to enter a command line but 
the terminal buffer is full and cannot accept it. This message is also 
issued when you attempt to use the 3270 COPY function anda printer is 
either not available or not ready. 


ADDITIONAL DISPLAY SCREEN CAPABILITIES 


The Extended Highlight feature and the Seven-Color feature are two added 
capabilities available for your use. Both features are available on the 
3279 Models 2 and 3. If you are using 3278 Model 2, 3, 4, or 5, the 
options for both features will be accepted. However, only the highlight 
feature will be operable. 


The CP SCREEN command (with its operands) allows you to chose one of 
three highlighting features (blinking, underscore, or reverse video) and 
one of seven different colors (red, green, blue, pink, turquois, yellow, 
or white) for each screen area. 


If you want the input area to. be read without highlighted, you should 
enter: 


CP SCREEN INAREA RED 


Or, if you want the input area read and the status area green with the 
blinking highlight, you should enter: 


CP SCREEN INAREA RED STATUS GREEN BLINK 
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For more details on the CP SCREEN command, see VM/SP CP Command 


| Reference for General Users, and more details on the terminal display 


areas, see VM/SP Terminal User's Guide. 


CONSOLE OUTPUT 


When you use a 3270 terminal as your virtual machine console, you do not 
ordinarily retain a console log, as you do on typewriter terminal. 
There may be many circumstances in which you need a printed record of 
your console output, whether it be to obtain a copy of program-generated 
output, or to retain a record of CP and/or CMS commands that resulted in 
an error condition. There are two techniques you can use in VM/SP to 
obtain hardcopy representations of display terminal sessions: spooling 
console output and the 3270 copy function. 


The CP SPOOL command provides the CONSOLE operand, which allows you to 
begin and end console spooling. You enter: 


cp spool console start 
when you want to begin recording your terminal session, and: 
cp spool console stop 


when you have finished. In between, you can periodically close the 
console file to release for printing whatever has been spooled thus far: 


cp spool console close 


Other operands that you can enter are the same as you might specify for 
any printer file, such as CLASS, COPY, CONT, and HOLD. 


An alternate technigue is to spool your console to your own virtual 
reader: 


cp spool console start * class a 


Then, when you close the console file, instead of being released to the 
CP printer spool file queue, it is routed to your virtual card reader, 
and you can load it onto your A-disk as a CMS disk file: 


readcard console file 


You can then use the editor to examine it (or to delete sections you 
don't need) and use the PRINT command to spool it to the printer. 


3270 COPY Function 


ED NEO EE 


If you are using a 3270 display terminal, and you have available a 3284, 
3286, 3287, 3288, or 3289 printer, you can copy the full screen display 
currently appearing on the screen. To copy the screen, you’ have to 
assign the copying function to a program function key, with the SET 
conmand: 
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cp set pf9 copy 


Note: The PF key copy function is not available if the printers are 
dedicated. 


Then, whenever you want to copy a screen display, you can press the PF9 
key (or whichever key you set). The display is printed on any 3270 
display printer that is attached to the same remote control unit as the 
display terminal. If, when you press the PF key, the screen status area 
indicates NOT ACCEPTED, it means that the printer is either not ready or 
not available. When you press the PF key and receive no response, it 
means that the screen has been copied. 


There is a print matrix available to the 3274 and 3276 user that 
allows control of the display to printer operations. In addition, a 
local print key is provided on the 3274 that can be used for copy 
operations. 


Figure 36 is an example of a 3270 screen display that could be copied 
on the printer. When you use the copy function to copy a screen, all 24 
lines of the display screen are copied; the screen status area 
(indicated as RUNNING in Figure 36) is blank if the 3270 is locally 
attached. If the 3270 is remotely attached, the entire screen including 
the screen status area, is copied. You can use the user input area of 
your screen to key in comments, or your name or userid, if several users 
are spooling copy files. 


DEFINE STORAGE 16384K 
STORAGE = 16384K 

IPL CMS 

VM/SP CMS — 01/30/80 


RUNNING 


Figure 36. 3270 Screen Display 


Signaling Interruptions 


The two keys on your 3270 keyboard that signal interruptions are the PA1 
key -- REQ key on a 3278 Model 2A -- and the Enter key. Throughout this 
publication, interruption signaling has been described in terms of the 
Attention key, which is the interruption signaling key on a 2741. 
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On a typewriter terminal, the Attention key, pressed once, causes a 
virtual machine interruption (if the terminal mode is set to VM); you 
must use it when you want to enter an Immediate command, such as HT or 
HX. Ona display terminal, you can enter these commands whenever your 
virtual machine is in a running status, without having to’. signal an 
interruption before you enter the command. 


Sometimes, however, if your terminal is displaying output very 
Tapidly, you must wait until the screen is full and the’ screen status 
area indicates a MORE... status before you attempt to enter the HT or HX 
command. 


The Enter key can also be used aS an interruption Signaling key. If 
you press it once when your virtual machine is running, you will place 
your virtual machine in the VM READ status, so you can enter a command 
line. 


An easier way to enter the CP environment is by pressing the PA1 key. 
Whenever you press this key, your virtual machine is placed in a CP READ 
status, and you can enter any CP command. From the CP environment, you 
must use the CP command BEGIN to resume execution of your virtual 
machine. 


HALTING SCREEN DISPLAYS 


When your terminal is displaying successive screens of output froma 
program or a CMS command, you can use the HT or HX Immediate commands to 
halt the display or the execution of the command, respectively. If your 
terminal is writing the information at a very rapid rate, you may have 
difficulty entering the HT or HX command. In these circumstances, you 
can use the PA1l key -- REQ key on a 3278 Model 2A -- or press the Enter 
key twice to force your terminal to a CP READ status. Then, you can use 
the CP command ATIN or REQUEST to signal a virtual machine read. When 
the screen status area indicates VM READ, you can enter HX or HT. 


Using the CMS Editor with a 3270 


The CMS Editor has a special format and operation, called display mode, 
that makes editing CMS disk files with a 3270 more convenient than ona 
typewriter terminal. It uses most of the display screen, and depending 
on the terminal type and model, displays, up to either 20 lines or 38 
lines of a file at once. In addition to displaying data lines of the 
file, the editor also indicates, on the topmost line of the screen, the 
filename, filetype, record format, and logical record length of the file 
being edited, as well as showing your current mode: input or edit. The 
format of the screen is Shown in Figure 37. 


The screen lines that you are most concerned with while editing are 
the current line, the user input area (the bottom two lines), and the 
editor's message line (the second line from the top) in which the 
editor's responses and error messages are displayed. The current line 
and the editor's message line are highlighted. 


When you first invoke the editor to edit a file, whatever is 
currently on the screen (including your EDIT command line) is erased and 
the full screen is controlled by the editor. The current line pointer 
is positioned at the top of the file, the top part of the display screen 
appears blank. The editor displays the characters "TOF:" and "EOF:" to 
indicate the top and end of the file, respectively. 
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| EDIT # DISPLAY SCREEN A12@ F 80 3 
>>>> 1 804 


TOFS Be 

THIS IS THE FIRST LINE OF THE FILE. (CURRENT LINE). @ o 
THIS IS THE SECOND LINE OF THE FILE. 

THIS IS THE THIRD LINE OF THE FILE. 

EOF: 


VM READ 


Notes: 

4% Edit session status. This indicates EDIT, INPUT, or NEW FILE. 
The NEW FILE message appears when you edit a new file; it is 
replaced with INPUT when you enter input mode and thereafter is 

_ EDIT or INPUT. 

2 The filename, filetype, and filemode of the file. 

# Record format and logical record length. 

* Editor reponse area. The response shown may be the response to 

_ a VERIFY subcommand entered with no operands. 

S$ The symbols TOF: and EOF: indicate top of file and end of file, 

_ respectively. 

© The current line is located in the approximate center of the 


output area of the screen. 
a eS | 


Figure 37. How the CMS Editor Formats a 3270 Screen 
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ENTERING EDIT SUBCOMMANDS 


When you enter an EDIT subcommand into the user input area and press the 
Enter key the subcommand is not displayed on the screen, but the change 
(or line pointer movement) is reflected in the screen display. If you 
enter a subcommand that moves the current line pointer, all of the lines 
on the screen are shifted up or down, according to the action taken by 
the subcommand. 


If you use the INPUT subcommand to enter input lines, the edit status 
field indicates INPUT; all of the lines that you enter are placed in the 
file and appear on the screen as the current line. (Entering input 
lines from a remote 3270 is somewhat different. The following "Editing 
on a Remote 3270" discusses the differences.) 

If you enter an invalid EDIT subcommand, or if you enter a subconmmand 
that requests information, the edit response appears inthe message 
field of the screen. For example, if you enter: 

trunc 


the editor responds by displaying the current truncation setting, which 
might be: 


>>>>> 81 
2 


If you enter: 
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copyfile myfile edit (trunc 
the editor would respond: 
>>>>> 7EDIT: copyfile myfile edit (trunc 


to indicate that it does not recognize the entered line (COPYFILE is not 
an EDIT subcommand). When you use line-number editing, the prompting 
message appears in this area; after you enter text in the user input 
area, the text line is written in the output display area, at_ the 
current line position. 


Two EDIT subcommands, CHANGE and ?, result in lines being copied in 
the user input area. In the case of the CHANGE subcommand, the line that 
is displayed is the current line. Once in the user input area, you can 
modify it and re-enter it. While you are changing it, the original line 
appears unchanged in the output display area. If you decide that you do 
not want changes entered, you must press the Erase Input key and then 
press the Enter key before you enter any other EDIT subcommands. 


You can use the ? subcommand to request that the last EDIT subcommand 
you entered be displayed in the user input area. If, for example, you 
enter a CHANGE or LOCATE subcommand that results ina NOT FOUND 
condition, or some other error, you can enter: 


2 


and modify the subcommand line and re-enter it, if you want; otherwise, 
use the Erase Input key to delete it. 


CONTROLLING THE DISPLAY SCREEN 


Usually the editor controls the entire screen display during an edit 
session. Occasionally, the screen goes into a MORE... Status, and you 
must use the Cancel key or PA2 key to clear the screen. There are two 
other situations in which the screen must be cleared, either by the 
editor, or by you. When you use the CMS subcommand to enter CMS subset 
to enter CMS commands, the screen is cleared and the message CMS SUBSET 
is displayed at the top of the screen. When you issue the subcommand 
RETURN to return to edit mode, the screen display is restored to its 
original appearance. 


The Situation is Slightly different, however, whenever you 
communicate with the control program (CP), or receive messages fron 
other users during an edit session. Any CP message or command response 


causes your screen to go into a MORE... status; you must use the PA2 
(Cancel) key to see the response. To restore your screen to its edit 
display, you should use the EDIT subcommand TYPE. If you use the PAT 
key to place your virtual machine in the CP environment, and the screen 
status area indicates CP READ, use the CP command BEGIN to restore edit 
mode. Then enter the TYPE subcommand. If you enter a subcommand other 
than TYPE, the entire screen is not restored, and the top two lines (the 
editor's data and response fields) tay contain lines of the CP response. 


If your virtual machine was in input mode when you entered the CP 
command, you may continue entering lines of input; the third through the 
ninth lines of the screen are restored after you enter the next line. 


If you enter a CP command that does not produce a response, then 
there is no change to the screen. 
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Verification Settings on a 3270 


The VERIFY subcommand allows you to alter the verification columns when 
you are editing a file or to cancel verification altogether. If, for 
example, you are editing a file with records longer than 80 characters, 
each line is displayed on two lines of the display screen. Sometimes, 
you may be editing only specific columns ina file, and do not need to 
see the lines displayed in their entirety. To see only the first 80 
columns, you could enter: 


verify 1 80 


Or, if you wanted to see the last 80 columns of a file with 
120-character records, you could enter: 


verify 41 120 If you cancel verification entirely by entering: 
verify off 


then modifications that you make to the file (including movement of the 
current line pointer) are not reflected on the display screen until you 
use the TYPE subcommand. 


THE CURRENT LINE POINTER 


There is one aspect of the CMS Editor on a 3270 that is much the same as 
on a typewriter terminal: you must still be concerned with the 
positioning of the current line pointer, and you can only add or modify 
data on the current line, even though you see many lines being 
displayed. The current line, on the screen, appears near the middle of 
the output area of the screen (see Figure 37). 


To move the current line pointer, you can use the subcommands UP and 
DOWN: UP indicates movement toward the top of the file and DOWN 
indicates movement toward the bottom of the file. When you issue either 
of these subcommands, the entire display of the file shifts down the 
screen (if you use the UP subcommand) or up the screen (if you use the 
DOWN subcommand) . 


If you have never used the CMS editor on a typewriter terminal, you 
may find the UP and DOWN subcommands confusing to use, so you can use 
instead the BACKWARD (UP) and FORWARD or NEXT (DOWN) subcommands' to 
shift the display backward (toward the top of the file) and forward 
(toward the bottom of the file). 


You can also use the EDIT subcommand SCROLL, which allows you to 
display successive screen displays, and to examine an entire file 
guickly. For instance, on a 3270 Model 2 display terminal, you enter 
the SCROLL subcommand with no operands, it is the equivalent of entering 
the subcommand DOWN (FORWARD) 20, which results in the screen changing 
to display the 20 lines following the lines currently being displayed. 
If you enter: 


scroll 10 


The SCROLL subcommand executes 10 times, placing the screen in a MORE... 
state at the end of each display. 


If the file you are editing has verification column settings greater 


than 80 characters (So each line takes up two display lines), then the 
SCROLL subcommand moves the screen 10 lines at once instead of 20. 


410 IBM VM/SP CMS User's Guide 


The UP (or BACKWARD) counterpart of SCROLL is SCROLLUP, which can be 
abbreviated SJ. 


USING PROGRAM FUNCTION (PF) KEYS 


You can enhance the use of the CMS editor ona 3270 by setting the 
program function (PF) keys on your terminal to correspond to some of the 
more frequently used EDIT subcommands, such as UP, DOWN, SCROLL, FILE, 
SAVE, and so on. You can also set a program function key to contain a 
line of data, so that if you are creating a file that has many duplicate 
lines in it, you can use the PF key instead of having to key in the 
entire line each time. 


You can set a program function key while you are in edit mode either 
by using the PA1 key -- REQ key on a 3278 Model 2A -- to enter the CP 
environment or by using the #CP function. 


USING THE EDITOR IN LINE MODE 


The editor's display mode is the most common format of operation ona 
3270. There are, however, instances when it is not possible or not 
desirable to use the editor in display mode. For these instances, you 
should use the line mode of operation, which is the equivalent to using 
a typewriter terminal. When you use line mode, each EDIT subcommand you 
enter, and the response (if you have verification on), is displayed, a 
line at a time, on the screen in the output display area. There is no 
full screen display of the file. 


You need only be concerned with using line mode if you are connected 
to VM/SP by a remote 3270 line, or if you are editing a file from within 
an EXEC and you want to control the screen display. Although it is 
possible to use the editor in line mode on a local 3270, it is rarely 
necessary for normal editing purposes. 


Editing on a Remote 3270 


When you invoke the editor from a remote 3270, you are placed in line 
mode by the editor. The advantage of using the 3270 in line node 
(particularly on a remote editor) is that the editor can respond more 
quickly to display reguests. When you use display mode, the editor has 
to write out the entire output display area when you move’ the current 
line pointer; in line mode, it has only to write a single line. 


If you want to use display mode, you enter the EDIT subcommand: 
format display 


The editor begins operating in display mode, and you can use the special 
editing functions available in display mode. 


However, when you are using a remote 3270 in display mode, and you 
enter the INPUT subcommand to begin entering input lines, the screen is 
cleared, and your input lines are displayed as if you were in line node, 
beginning at the top of the screen. When you enter a null line to return 
to edit mode, the editor returns to a full screen display. 
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You can resume editing in line mode by using the subcommand: 


format line 


Editing From a CMS EXEC File 


If you invoke the editor from a CMS EXEC, but you do not want the screen 
cleared when the editor gets control, you can specify the NODISP option 
on the EDIT command line: 


edit test file (nodisp 


This places the 3270 in line mode, so that the lines already on the 
screen are not erased. 


The 3270 remains in line mode for the remainder of the edit session, 
and you cannot use the FORMAT subcommand to place it in display mode. 


USING SPECIAL CHARACTERS ON A 3270 


There are two special characters available on a typewriter terminal 
whose functions have no meaning on a display terminal. They are the tab 
Character (X'05') and the backspace character (X'16'). For most file 
creation and editing purposes, you will probably not need to’ use the 
backspace, but many CMS filetypes use tab settings to set up the proper 
column alignment in files. There are two methods you can use to enter 
any special character on a 3270 (including tabs), andan additional 
method of using tabs, which involves setting a program function key. In 
addition, the tab character can also be set via the CP command TERMINAL 
TABCHAR. 


To enter any special character (a backspace is used in this example) 
you can either: 


1. Enter another character at the appropriate place in the record, and 
then use the ALTER subcommand to alter that character to. the 
hexadecimal value of the character you want to represent (a 
backspace character is a X'16'). For example: 


input ABC>>> 
alter > 16 1 * 


When you enter backspaces and overstrike characters ona 3270, 
however, the characters and backspaces each occupy character 
positions, so that a single compound character occupies three 
character positions on the screen. If the image setting is CANON, 
and you want to use the backspace to enter compound characters, you 
must not enter the backspace character first. 


2. Before you begin to create the file, use the CMS SET command to 
define some other character as the backspace character: 


set input > 16 
CMS then translates all occurrences of the character > to X'16'. 
If you need to correct a line that contains backspaces, you’ can 


reverse the above seguence; alter the X'16' characters to asterisks and 
enter the CHANGE subcommand. 
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Defining a 3270 Program Function Key for Tab Settings 


You can set up a program function key to operate like a tab key ona 
typewriter terminal. You must use the CP SET command as follows: 


SET PFnn TAB nl n2.. .nn 
where: 
PFnn is any valid function key from PF1 to PF24. 


n1n2...nn are the logical tab settings desired, expressed as decimal 
numbers. Invalid tab settings are ignored. You can specify 
the setting values in any order, but they are normally 
specified in ascending order. 


You can define different PF keys with different tab settings for 
different filetypes. Whenever you press the PF key you have’ set fora 
tab, the cursor moves to the corresponding position in the user input 
area, in much the same way that a typing element ona typewriter would 
move to the next tab stop. 


If you press the PF tab key to a position that already contains a 
data character, the data remains intact. If there is no data in that 
position, a tab character is entered in the file. The effect of the tab 
in the file depends, as in normal usage, on the image setting of the 
editor. If the image setting is set to on (the default), the tab expands 
to an appropriate number of blanks, to correspond to the settings in 
effect for the TABSET subcommand. When the TABSET settings match the 
tab settings of the PF key, then any lines you enter in the user input 
area appear exactly as they will appear in the output display area. 


Changing and Displaying Special Characters 


When you edit a file on a 3270 terminal in display node, you should not 
copy a line containing tabs or backspaces into the user input area. The 
tabs or backspaces are converted to blanks (X'40'). Similarly, if the 
line contains VM/SP logical line editing symbols that have been entered 
as data characters, the symbols are reinterpreted when you enter the 
line. 


If you use the SET OUTPUT function to display nonprintable characters 
in CMS, the character translations do not appear when the editor is in 
display mode. They are, however, displayed when the editor is in line 
mode. 


Using APL with a 3270 


If you have a 3277 or 3278 display station equipped with an APL 
keyboard, you can use APL on a 3270 terminal in CMS. You invoke the APL 
virtual machine by issuing the command specified in the VSAPL Progran 
Product documentation. This command invokes the VSAPL-CMS interface 
program. You are then frompted to press the APL On/Off key which is on 
your terminal; pressing this key changes the keyboard to APL character 
input mode. You are then prompted to press the Enter key to continue. 


EBCDIC or APL characters can always be displayed; the APL On/Off key 


does not’ change this. The VSAPL-CMS interface program issues’ the 
TERMINAL APL ON command for you and selects the appropriate translation 
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tables. The TERMINAL APL ON command automatically forces a TERMINAL 
TEXT OFF condition. The interface program then invokes the VSAPL 
program. When the VSAPL ready message appears on the screen, you can 
use APL. 

You can send a copy of your display screen to a locally or renotely 
attached printer. Be sure that the printer you send your output to has 
the APL feature installed; if it does not, the APL characters are not 
printed. Most system printers do not have an APL print chain; therefore 


you may need to use the copy function to direct your screen output 
displays to a 3284, 3286, or 3287 printer. 


ERROR SITUATIONS 
If you do not have the APL hardware feature installed on your 3277 or 
3278 but you invoke APL: 


e The VSAPL program is invoked and the TERMINAL APL ON command is 
issued. 


e You cannot communicate with the VSAPL progran. 
e Any APL characters that are written to the screen appear as blanks. 
If you have the APL feature installed on your terminal, but invoke 

APL manually without issuing the TERMINAL APL ON command or issue 
TERMINAL APL OFF at sometime during APL processing: 

e The VSAPL program is activated. 

e You cannot communicate with the VSAPL progran. 

e Any APL characters written to the screen appear as blanks. 
If you attempt to use the APL O/S (overstrike) key when the APL 


hardware key is set off, it acts as a backtab key and repositions the 
cursor to the beginning of the user input area. 


LEAVING THE APL ENVIRONMENT 


Issue the APL commands: 
) OFF 
to log off VM/SP. 
Issue the APL command: 
) OFF HOLD 
to return to CMS. This APL command invokes the VSAPL-CMS interface 
progran, which: 
e Issues the TERMINAL APL OFF command 
e Prompts you to press the APL hardware key 


e Returns to CMS 
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Note: The APL hardware feature is a key, not a switch. Each time you 
press the APL key you reverse its on/off setting. To determine whether 
APL is on or off, press a key that represents a special APL character. 
If the character displayed is an APL character, the hardware APL feature 
is set on. If the character displayed is a non-APL character, you must 
press the APL key once to set the APL feature on. 


Using the 3277 Text Feature 


If you have a 3277 or 3278 display station equipped with the Data 
Analysis Text keyboard, you can key in, as well as display, all of the 
special text characters. For a description of these characters, see the 
VM/SP Terminal User's Guide. These characters are in addition to those 


available with standard EBCDIC 3270 terminals. If you have a suitably 
equipped printer attached to your 3270, you can use the SET PFnn COPY 
function to obtain a printed copy of the screen. 


When you want to activate the text feature, and use the special 
characters, enter the command: 


cp terminal text on 
The TERMINAL TEXT ON command automatically forces the TERMINAL APL OFF 


command. Now, you can use any of the special characters when you enter, 
change, or locate text lines in a file. 


ERROR SITUATIONS 


If you do not have the appropriate text hardware feature on your 3270, 
but attempt to display a file that contains the characters, the 
characters appear as blanks on a 3277, and as hyphens on a 3276 anda 
3278. 

If you inadvertently issue the TERMINAL TEXT ON command while using a 
terminal that does not have the text capability, you must do the 
following to return to normal operating procedures: 

1. Press the PA1l key to enter the CP environment. 
2. Key in, in uppercase letters only, the command line: 


TERMINAL TEXT OFF You leave the special text environment by 
entering the command: 


cp terminal text off 


LEAVING THE TEXT ENVIRONMENT 


You leave the special text environment by entering the command: 
cp terminal text off 
Notes 
1. The 3270 text hardware feature is activated by a key, not a switch. 


Each time you press the TEXT OnyOff key, you reverse its setting. 
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When the red light on the text keyboard is illuminated, the text 
feature is on. 


Compound characters, such as a character/backspace/character 
combination, are still entered and displayed as’ three characters. 
The screen position occupied by the backspace character appears as 
a blank because the character (X'16") is nondisplayable. 
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Appendix D. Sample Terminal Sessions 


This appendix provides sample terminal sessions showing you how to use: 


The CMS Editor (using context editing), and the CMS COPYFILE, SORT, 
RENAME, and ERASE commands 


The CMS Editor (using line-number editing) 


CMS OS simulation to create, assemble, and execute a program using OS 
macros in the CMS environment 


CMS VSE/AF simulation to create, assemble, and execute a program 
using macros in the CMS/DOS environment. 


Access method services under CMS, to create VSAM catalogs and data 
spaces, and to use the define and repro functions of AMSERV 
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Sample Terminal Session Using the CMS Editor and CMS File System Commands 


This terminal session shows you how to create a CMS file and make changes to it using the 
CMS Editor, and then manipulate it using the CMS file system commands, COPYFILE, ERASE, 
RENAME, and SORT. 


Note: Throughout this terminal session whenever a TYPE subcommand or command is issued 
that results in a display of the entire file, the complete display is not shown; omitted 
lines are indicated by vertical ellipses (...). When you enter the TYPE command or 
subcommand, you should see the entire display. 


1 edit command data 
NEW FILE: 
EDIT: 
2 image 
ON 
tabs 1 12 80 
trunc 72 
3 input 
INPUT: 
copyfile copy cms files 
sort sort cms files in alphameric order by specific columns 
edit create a cms file 
edit modify a cms file 
renane change the name of a cms file 
punch punch a copy of a cms file on cards 
print print a cms file 
erase erase a cms file 
listfile list informaticn on a cms file 
state verify the existence of a cms file 
statew verify the existence of a cms file on a read/write disk 
readcard read a cms file from your card reader onto disk 


disk dump punch a cms file in cms disk dump format into your virtual card punch for 


4 TRUNCATED 
DISK DUMP PUNCH A CMS FILE IN CMS DISK DUMP FORMAT INTO YOUR VIRTUAL CA 
disk load read a disk dump file onto disk 
compare compare the contents of cms disk files 
tape dump dump cms files onto tape 
tape load read cms files onto disk from tape 


EDIT: 


1 Use the EDIT command to invoke the CMS Editor to create a file with a filename of 
COMMAND and a filetype of DATA. Since the file does not exist, the editor issues 
the message NEW FILE. 

2 Check that the image setting is ON. This is the default for all filetypes except 
SCRIPT. Then, set the logical tab stops for this file at 1, 12, and 80, and seta 
truncation limit of 72. 

3 Enter the subcommand INPUT to enter input mode and begin entering lines in the file. 
For these input files, you should press the Tab key (or equivalent) on your terminal 
following each CMS command name. If there is a physical tab stop on your terminal 
in column 12, the input data appears aligned. 


4 The message, TRUNCATED, indicates that the line you just entered exceeded the 
truncation limit you set for the file (column 72). The editor displays the line, so 
you can see how much of the line was accepted. Your virtual machine is still in 
input mode, so continue entering input lines. 

5 To get out of input mode, enter a null line (press the Return or Enter key without 


entering any data). The editor responds with the message EDIT:. 
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12 


13 


10 


11 
12 
13 


top 

TOF: 

type * 

TOF: 

COPYFILE COPY CMS FILES 


TAPE LOAD READ CMS FILES ONTO DISK FROM TAPE 

EOF: 

locate /disk dump 

DISK DUMP PUNCH A CMS FILE IN CMS DISK DUMP FORMAT INTO YOUR VIRTUAL CA 
replace disk dump punch a cms file onto cards 


input 

INPUT: 

type display the contents of a cms file at your terminal 
renane alter the name of a cms file 

sort resequence the records in a cms file 
copyfile reformat a file, by columns 

comprae verify that two files are identical 
EDIT: 

change /rae/are/ 

COMPARE VERIFY THAT TWO FILES ARE IDENTICAL 
bo 

TAPE LOAD READ CMS FILES ONTO DISK FRCM TAPE 
input 

INPUT: 

EDIT: 

file 

R; 


Use the TOP subcommand to position the current line pointer at the top of the file. 
The editor responds TOF:. 

Use the TYPE subcommand to display the entire file. Note that all of your input 
lines are translated to uppercase characters, and that the tab characters you 
entered have been expanded, so that the first word following each command name 
begins in column 12. 

The message EOF: indicates that the end of the file is reached. You can issue the 
LOCATE subcommand to locate a line. Since you are at the bottom of the file, the 
editor begins searching from the top of the file. Notice that you can enter the 
character string you want to locate in lowercase characters; the editor translates 
it to uppercase to locate the line. The editor displays the line. 

Use the REPLACE subcommand to replace this line, in a shortened form so that it is 
not truncated. Rememkrer to enter a tab character after the command name; when you 
enter the line, the tab stop does not have to be in column 12. Then, use the INPUT 
subcommand again to resume entering input. The lines that you enter next are written 
into the file following the DISK DUMP line. 

When you make a spelling error or other mistake, you may s-want to correct it 
immediately. Fnter a null line to return to edit mode, and use the CHANGE subcommand 
to correct the error. In this example, the string RAE is changed to ARE. The 
editor displays the line as changed. 

Use the BOTTOM subcommand to move the current line pointer to point to the last line 
in the file. Enter input mode with the INPUT subcommand. 

If you enter input mode and decide that you do not want to enter input lines, all 
you have to do to return to edit mode is enter a null line. 

To write the file onto disk, use the FILE subcommand. This writes it onto disk 
using the name with which you invoked the editor, COMMAND DATA. The CMS ready 
message indicates that you are in the CMS command environment. 
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type command data 


COPYFILE COPY CMS FILES 
SORT SORT CMS FILES IN ALPHAMERIC ORDER BY SPECIFIC COLUMNS 


TAPE LOAD READ CMS FILES ONTO DISK FROM TAPE 
R; 

edit command data 

EDIT: 

save 

EDIT: 

fname conm2 

file 

R; 

copyfile comm2 data a (lowcase 

R; 

copyfile command data a comm2 data a (ovly specs 
DMSCPY601R ENTER SPECIFICATION LIST: 

1-12 1 

Rj 

type comm2 data 


COPYFILE Copy cms files 


SORT Sort cms files in alphameric order by specific columns 
EDIT Create a cms file 

EDIT Modify a cms file 

RENAME Change the name of a cms file 

PUNCH Punch a copy of a cms file on cards 

PRINT Print a cms file 

ERASE Erase a cms file 

LISTFILE List information on a cus file 

ht 

R; 


To display the entire file at your terminal, use the CMS TYPE command. Note any 
errors that you made that you might want to correct. 

Use the EDIT command to edit the file COMMAND DATA again. This time, since the file 
exists, the editor does not issue the message, NEW FILE: 

While you are in edit mode, make any changes that you need to; then issue the SAVE 
subcommand to save these changes, and replace the existing copy of the file onto 
disk. 

Use the FNAME subcommand to change the filename of the file to COMM2 (the filetype 
remains unchanged). When you issue the FILE subcommand this time, the file is 
written onto disk with the name COMM2 DATA. 

You can rewrite the entire file, COMM2 DATA in lowercase characters, using the 
COPYFILE command with the LOWCASE option. 

The file COMM2 DATA is now all lowercase characters (you can display the file with 
the TYPE command if you want to verify it). However, the command names, and the 
first character of the description should be uppercase characters. You can use the 
COPYFILE command again, to overlay the original uppercase characters of COMMAND DATA 
in columns 1 through 12 over the lowercase characters in columns 1 through 12 of 
COMM2 DATA. 

Use the TYPE command to verify that the COPYFILE command did, in fact, overlay only 
the columns that you wanted. 

The HT Immediate command suppresses the display of the remainder of the file; you 
can see from the first few lines that the format of the file is correct. 
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listfile * data 


COMMAND DATA Al 
COMM2 DATA Al 
R; 


sort comm2 data a command sort a 
DMSSRT604R ENTER SORT FIELDS: 


tT. 

R; 

type command sort 

COMPARE Verify that two files are identical 

COMPARE Compare the contents of cms disk files 

TYPE Display the contents of a cms file at your terminal 
Rs 


copyfile comm2 data a function data a ( specs 
DMSCPY601R ENTER SPECIFICATION LIST: 

12-72 1 1-39 70 

R; 

type function data 


Copy cms files COPYFILE 
Sort cms files in alphameric order by specific columns SORT 

Read cms files onto disk from tape TAPE LOAD 
R; 


sort function data a functicn sorta 
DMSSRT604R ENTER SORT FIELDS: 


1 70 

R; 

type function sort 

Alter the name of a cms file RENAME 
Change the name of a cms file RENAME 
Verify the existence of a cms file on a read/write disk STATEW 
R; 


The LISTFILE command lists your two files with the filetype of DATA. (If you 
previously had files with these filetypes, they are also listed.) 

To sort the file CCMM2 DATA into alphabetic order, by command, issue the SORT 
command. When you are frompted for the sort fields, enter the columns that contain 
the command names, 1 through 9. 

The output file from the SORT command is named COMMAND SORT. You can use the TYPE 
command to verify that the records are now sorted alphabetically by command. 

To create another copy of the file, this time with the command names on the right 
and the functional description on the left, use the COPYFILE command with the SPECS 
option again. To create a file this way, you must know the columns in your input 
file (COMM2 DATA) and how you want them arranged in your output file (FUNCTION 
DATA). Columns 1 through 9 contain the command names; columns 12 through 72 contain 
the descriptions. The specification list entered after the prompting message 
indicates that columns 12 through 72 should be copied and placed beginning in colunn 
1, and that columns 1 through 9 should be copied beginning in column 70. 

Verify the COPYFILE operation with the TYPE command. 

Sort the file FUNCTION DATA so that the functional descriptions appear in alphabetic 
order. You may also want to display the output file, FUNCTION SORT. 
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listfile 
COMMAND DATA Al 
COMM2 DATA Al 
COMMAND SORT Al 
FUNCTION DATA A1 
FUNCTION SORT A1 
R5 
erase command data 
R; 
rename comm2 data a command data a 
R; 
listfile * * a ( label 
FILENAME FILETYPE FM FORMAT LRECL RECS BLOCKS DATE TIME LABEL 
FUNCTION SORT Al F 80 22 3 10/13/75 7:52:03 ABC191 
COMMAND DATA Al F 80 22 3 10/13/75 7:48:52 ABC191 
COMMAND SORT Al F 80 22 3 10/13/75 7:48:15 ABC191 
FUNCTION DATA Al F 80 22 3 10/13/75 7:51:37 ABC191 
R3 
edit function sort 
EDIT: 
zone 

1 80 
zone 60 
Change / // * 
Alter the name of a cms file RENAME 
Change the name of a cms file RENAME 
Verify the existence of a cms file on a read/write disk STATEW 
EOF: 
top 
TOF: 
find List 
NOT FOUND 
EOF: 
case 

U 
case 
find List 
List information on a cms file LISTFILE 


If these are the only files on your 


A-disk, the LISTFILE command entered with no 


operands produces a list of the files created so far. 


The file COMM2 was 
Since you no longer need the original 
Use the RENAME 
DATA. The LISTFILE command verifies t 


created for a workfile, in case any 


command to rename the workfile 


errors might have happened. 
you can erase it. 
the name COMMAND 


file, COMMAND DATA, 
COMM2 DATA to have 
he change. 


To begin altering the file FUNCTION SORT, invoke the editor again. 


The ZONE command requests a display of 
1 and 80. 
and 80, so that you cannot modify data 


The CHANGE subcommand requests that the 
be compressed. 


on each line in the file 
CHANGE request by displaying each line 
net effect is to shift the command col 
Position the current line pointer at 
subcommand to move the line pointer to 
The editor indicates that the line is 
the CASE subcommand, you can see that 
the editor is translating your input 


When you issue the command ZONE 


the current zone settings, which are columns 

60, it changes the settings to columns 60 

in columns 1 through 59. 

first appearance of five consecutive blanks 
The editor displays the results of this 


changed (which is each line in the file). The 
umn 5 spaces to the left. 
the top of the file, and then issue a FIND 


the line that begins with "List". 

not found. Checking the current setting for 
it is U, or uppercase, which indicates that 
data to uppercase. You can issue the CASE 4&4 


subcommand to change this setting, then reissue the FIND subcommand. 
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Change /on a cms/about a CMS 


NOT FOUND 

= zone 1 * 

List information about a CMS file LISTFILE 
top 

TOF: 

change /cms/CMS/ * 

Alter the name of a CMS file RENAME 
Change the name of a CMS file RENAME 
Verify the existence of a CMS file on a read/write disk STATEW 
EOF: 

save 

EDIT: 

top 

TOF: 

next 

Alter the name of a CMS file RENAME 
$dup 

Alter the name of a CMS file RENAME 
change /name/filetype/ 

Alter the filetype of a CMS file RENAME 
next 

Change the name of a CMS file RENAME 
change /nane/filename/ 

Change the filename of a CMS file RENAME 
next 

Compare the contents of CMS disk files COMPARE 
next 

Copy CMS files COPYFILE 
find M 

Modify a CMS file EDIT 

up 

List information about a CMS file LISTFILE 
i Make a copy of a CMS disk file COPYFILE 
top 

TOF: 


The editor locates the line and displays it. You want to change the character string 
"on a cms" to "about a CMS". The editor does not find the string you specify because 
the zone setting for columns 60 through 80 is still in effect. You can enter the 
ZONE subcommand, and reissue the CHANGE subcommand, or you can enter the = (REUSE) 
subcommand to stack the CHANGE subcommand, and enter the ZONE subcommand to execute 
first. 

The ZONE subcommand is executed, then the CHANGE subcommand. The editor displays the 
changed line. 

At the top of the file, enter another global change request, to change lowercase 
occurrences of the string cms to uppercase. The editor displays each line changed. 
When the EOF: message indicates that the end of the file is reached, you can save 
the changes made during this edit session with the SAVE subcommand before 
continuing. 

Move the current line pointer to point to the first line in the file. You want to 
add an entry that is similar; use the $DUP edit macro to duplicate the line, then 
change the copy that you made of the line. 

You can change the word name to filename in the next line also. 

You can scan a file, a line at a time, by issuing successive NEXT subcommands. 

To insert a line beginning with the character MM, and to maintain alphabetic 
sequencing, use the FIND subcommand to find the first line beginning with an M. The 
line to be inserted begins with the characters MA, so you want to move the line 
pointer up. 

You can insert a Single line into a file with the INPUT subcommand. Here, the INPUT 
subcommand is truncated to I, so that when you space over to write the command hame 
in the right column, you can align it (ycu only have to allow for the two character 
Spaces use by "i ", 
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/COPYFILE 

Copy CMS files COPYFILE 
n 

Create a CMS file EDIT 

n 

Display the contents of a CMS file at your terminal TYPE 


n 
Dump CMS files onto tape TAPE DUMP 
n 

Erase a CMS file ERASE 

up 3 

Create a CMS file EDIT 

i Delete a file from a CMS disk ERASE 
file 

R; 

type function sort a 


Alter the name of a CMS file RENAME 
Alter the filetype of a CMS file RENAME 
Change the filename of a CMS file RENAME 


Verify the existence of a CMS file on a read/write disk STATEW 


R; 

edit function sort 

zone 58 

change / // * * 

Alter the name of a CMS file RENAME 
Alter the filetype of a CMS file RENAME 
Change the filename of a CMS file RENAME 


Verify the existence of a CMS file on a read/write disk STATEW 
EOF: 


top 

TOF: 

change //| / * 

Alter the name of a CMS file | RENAME 
Alter the filetype of a CMS file | RENAME 
Change the filename of a CMS file | RENAME 
Verify the existence of a CMS file on a read/write disk | STATEW 
EOF: 


a ee ee a 


Move the line pointer to the top of the file and begin scanning again. A diagonal 
(/) is interpreted as a LOCATE subcommand. 

The NEXT subcommand can be truncated to "N", 

In front of the line beginning "Display", insert a line beginning with "Delete". If 
you want to make any other modifications, do so. Otherwise, write this file onto 
disk with the FILE subcommand. 

Verify your changes. 

Edit the file again. To compress unnecessary spaces in right hand columns, change 
the zone setting. This time, issue a CHANGE subcommand that will delete all blank 
Spaces occuring after column 58. Since some changes you made to the file might have 
spoiled the alignment in the command column, this CHANGE subcommand should realign 
all of the columns. 

Return the current line pointer to the top of the file. Change a null string to the 
string "| " for all lines in the file; since the left zone is still column 58, the 
characters are inserted in columns 58 and 59. 
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zone 1 * 

top 

TOF: 

c //| / * 

{| Alter the name of a CMS file | RENAME 
| Alter the filetype of a CMS file {| RENAME 
| Change the filename of a CMS file | RENAME 


| Verify the existence of a CMS file on a read/write disk | STATEW 
EOF: 

top 

TOF: 

next 

| Alter the name of a CMS file | RENAME 
tabset 72 

repeat * 

overlay { 

| Alter the name of a CMS file 

| Alter the filetype of a CMS file 

| Change the filename of a CMS file 

| Compare the contents of CMS disk files 


RENAME | 
RENAME 
RENAME 
COMPARE | 


| Verify the existence of a CMS file on a read/write disk | STATEW | 
EOF: 

botton 

| Verify the existence of a CMS file on a read/write disk | STATEW | 


R; 
print function sort 
R; 


Change the left zone setting to column 1 and let the right zone be equal to the 
record length; issue the CHANGE subccmmand to insert the "| ™ in columns 1 and 2. 
CHANGE can be abbreviated as "C", 

At the top of the file, change the TABSET subcommand setting to 72. This makes 
column 72 the left margin. The REPEAT * subcommand, followed by the OVERLAY 
subcommand, indicates that all the lines in the file are to be overlaid with a | in 
the leftmost column (column 72). 

When you enter this INPUT subcommand, enter a number of blank spaces following it; 
this places a blank line in the file. 

Reset the ZONE setting to columns 1 and 72. The CHANGE subcommand indicates that all 
blanks on this line should be changed to hyphens (-). Only the blanks within the 
specified zone are changed. 

Insert another blank line at the top of the file and change it to hyphens. 

Write the file onto disk and use the CMS PRINT command to spool a ocopy to the 
offline printer. 
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Sample Terminal Session Using Line-Number Editing 


This terminal session shows how a terminal session using right-handed line-number editing 
Night appear on a typewriter terminal. The commands function the same way ona display 
terminal, but the display is somewhat different. When you enter these input lines, you 
should have physical tab stops set at your terminal at positions 16 and 22 (for assembler 
columns 10 and 16; the difference compensates for the line numbers, as you will see). On 
a display terminal, tab settings have no significance; once the line is in the output 
display area, it has the proper number of Spaces. 


1 edit test assemble 
NEW FILE: 
EDIT: 
2 linenode right 
input 
INPUT: 
3 00010 * sample of linemode right 
00020 test csect 
00030 balr 12,0 
00040 using *,12 
00050 st 14,sav14 
00060 wrterm testing... 
00070 1 14,sav14 
00080 br 14 
00090 end 
00100 
4 
EDIT: 
5 60 
00060 WRTIERM TESTING... 
6 c /testing.../'testing...! 
00060 WRTIERM '"TESTING...! 
7 80 
00080 BR 14 
input 
INPUT: 
1 Use the EDIT command to invoke the CMS Editor. Since this is a new file, the editor 
issues the NEW FILE message. 
2 Issue the LINEMODE subcommand to indicate that you want to begin line-nunmber 


editing. For ASSEMBLF files, you cannot have line numbers on the left, because the 
assembler expects data in columns 1 through 7. 


3 AS soon as you issue the INPUT subcommand, the editor begins prompting you to enter 
input lines. For convenience in entering lines, the line numbers appear on the left, 
as they would if you were using left-handed line-number editing. In your ASSEMBLE 
file, however, the line numbers are actually on the right. 

4 When you are have finished entering these input lines, enter a null line to return 
to edit mode from input mode. 

5 To locate lines when you are using line-number editing, you can enter the line 


number of the line. In this case, enter 60 to position the current line pointer at 
the line numbered 00060. ‘The editor displays the line. 


6 Issue the CHANGE subcommand to place guotation marks around the text line for the 
WRTERM macro. The editor redisplays the line, with the change. 
7 Issue the nnnnon subcommand, specifying line number 80, and use the INPUT subcommand 


so you can begin entering more input lines. 
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16 


10 
11 


12 


13 


14 
15 


16 


00083 sav14 ds £ 

00085 wkarea ds 3d 

00087 flag ds x 

00088 runon equ x'80! 

00089 runoff equ x40! 

RENOUMBER LINES 

EDIT: 

linemode off 

serial abc 

save 

EDIT: 

linemode right 

type 

00130 RUNOFF EQU x*'4o? 

verify 1 * 

type 

00130 RUNOFF EQU X'4o? ABC00130 
135 runmnix egu x'20' 
50 

00050 ST 14,SAV14 ABCO00050 
input 

INPUT: 

00053 tm flag,runon 
00055 ber 1,14 

00057 


EDIT: 

top 

TOF: 

next 

* SAMPLE OF LINEMODE RIGHT ABC00010 
restore 


When you begin entering input lines between two existing lines, the editor uses an 
algorithm to assign line numbers. 

The editor ran out of line numbers, since the next line in the file is already 
numbered 90. You must renumber the lines. Before you can renumber the lines, you 
must turn line-number editing off. Before issuing the SAVE subcommand, which writes 
the file and its new line numbers onto disk, you can issue the SERIAL subcommand. 
SERIAL ABC indicates that you want the characters ABC to appear as the first three 
characters of each serial number. 

The EDIT message indicates that the SAVE request has completed. 

Issue the LINEMODE subcommand to restore line-number editing. Use the TYPE 
subcommand to verify the position of the current line pointer. 

If you want to see the serial numbers in columns 72 through 80, issue the VERIFY 
subcommand, specifying *, or the record length. Normally, the editor does not 
display the columns containing serial numbers while you are editing. 

You can use the nannn subcommand to insert individual lines of text. This subcommand 
inserts a line that you want numbered 135, and places it in its proper position in 
the file. Note that although, in this example, the current line pointer is 
positioned at line 130, it does not need to be at the proper place in the file. When 
the subcommand is complete, however, the current line pointer 1s positioned 
following the line just inserted. 

Position the line pointer at the line numbered 50, and again begin entering the 
input lines indicated. 

Enter a null line to return to edit mode, move the current line pointer to the top 
of the file, and display the first line. 

The RESTORE subcommand restores the default settings of the editor, and the the 
verification columns are restored to 1 and 72, so that line numbers are not 
displayed in columns 72 through 80. 
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type * 
* SAMPLE OF LINEMODE RIGHT 
TEST CSECT 
BALR 12,0 
USING *,12 
ST 14,SAV14 
TM FLAG, RUNON 
BCR 1,14 
WRTERM ‘'TESTING...!' 
L 14,SAV14 
BR 14 
SAV14 DS F 
WKAREA DS 3D 
FLAG DS X 
RUNON EQU X*' 80! 
RUNOFF EQU XK'4Q? 
RUNMIX EQU X' 20° 
END 
EOF: 
linemode right 
file 
RESERIALIZATION SUPPRESSED 
R; 
type test assemble 
* SAMPLE OF LINEMODE RIGHT ABC00010 
TEST CSECT ABC00020 
BALR 12,0 ABC00030 
USING *,12 ABCO0040 
ST 14,SAV14 ABC00050 
TM FLAG, RUNON 00053 
BCR 1,14 00055 
WRTERM 'TESTING...' ABCO0060 
L 14,SAV14 ABC00070 
BR 14 ABC00080 
SAV14 DS F ABC00090 
WKAREA DS 3D ABC00100 
FLAG DS X ABC00110 
RUNON EQU xX'80! ABC00120 
RUNOFF EQU KX" 4Q? ABC00130 
RUNMIX EQU X*20! 00135 
END ABC00140 


Use the TYPE subcommand to display the file. 

When you issue the FILE subconmmand to write the file onto disk, the editor issues 
the message RESERIALIZATION SUPPRESSED to indicate that it is not going to update 
the line numbers, so that the current line numbers match the line numbers as they 
existed when the SAVE subcommand was issued. 

If you want to see how the file exists on disk, use the CMS TYPE command to display 
the file. Note that the lines inserted after the SAVE subcommand do not’ have the 
initial ABC characters, and that they retain the line numbers they had when they 
were inserted. 
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Sample Terminal Session For OS Programmers 


The following terminal session shows how you might create an assembler language program 
in CMS, assemble it, correct assembler errors, and execute it. All the lines that appear 
in lowercase are lines that you should enter at the terminal. Uppercase data represents 
the system response that you should receive when you enter the command. 


The input data lines inthe example are aligned in the proper columns for the 
assembler; if you are using a typewriter terminal, you should set your’ terminal's tab 
stops at columns 10, 16, 31, 36, 41, and 46, and use the Tab key when you want to enter 
text in these columns. If you are using a display terminal, when you use a PF key defined 
as a tab, or some input character, the line image is expanded as it is placed in the 
screen output area. 


There are some errors in the terminal session, so that you can see how’ to correct 
errors in CMS. 


1 edit ostest assemble 
NEW FILE: 
EDIT: 
input 
INPUT: 
dataproc csect 
print nogen 


Space 
r0 equ 0 
r1 equ 1 
r2 equ 2 
r19 equ 10 
r12 equ 12 
r13 equ 13 
r14 equ 14 
r15 equ 15 
space 
stm r14,r612,12(r13) save caller's regs 
balr 1£12,0 establish 
using *,r12 addressability 
st r13,saveareat4 store addr of caller's savearea 
la r15,savearea get the address of my savearea 
st r15,8 (r13) store addr in caller's savearea 
1r r13,r15 save addr of my savearea 
space 
*open files and check that they opened okay 
space 
la r3,0 initially set return code 
open (indata,outdata, (output) ) open files 
using ihadcb,r10 get dsect to check files 
la r10,indata prepare to check output file 
tn dcboflgs,x'10" everything ok? 
bnz checkout e- continue 
la r3,100 set return code 
b exit wow eXkLt 
checkout la r10,outdata check output file 
tm dcbhoflgs,x'10" is it okay? 
bnz process ene 
la r3,200 set return code 
b exit 
space 
process equ * 
get indata read a record from input file 
1 The EDIT command is issued to create a file named OSTEST ASSEMBLE. Since the file 


does not exist, the editor indicates that it is a new file and you can use the INPUT 
subcommand to enter input mode and begin entering che input lines. 
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lr r2,r1 save address of record 


put outdata, (2) hove it to output 
b process continue until end-of-file 
space 
exit equ * 
close (indata,,outdata) close files 
1 r13,saveareat4¥ addr of caller's save area 
lr r15,r3 load return code 
1 r14,12 (r13) get return address 
lm r0,r612,20{r13) restore regs 
br r14 bye... 
space 
savearea dc 18£'O! 


indata dcb ddname=indd,macrf=gl,dsorg=ps,recfm=f,lrecl=80, 


EDIT: 
$mark 
save#finput 
EDIT: 
INPUT: 
eodad=exit 
outdata dcb ddname=outdd, macrf=pn,dsorg=ps 


dcbd 
space 
end 

EDIT: 

file 

R; 

global maclib osmacro 

R; 

assemble ostest 

* 

* 

* 

* 

* 

* 

4 


Since the DCB macro statement takes up more than one line, you have to enter a 
continuation character in column 76&.. To do this, you can enter a null line to 
return to edit mode and execute the $MARK edit macro, which places an asterisk in 
column 7&.. If the S$MARK edit macro is not on your system, you will have to enter a 
continuation character some other way. (See "Entering a Continuation Character in 
Column 72" in "Section 5. The Editors.") 

Before continuing to enter input lines, the EDIT subcommand SAVE is issued to write 
what has already been written onto disk. The CP logical line end symbol (#) 
separates the SAVE and INPUT subcommands. 

A null line returns you to edit mode. You may wish, at this point, to proofread 
your input file before issuing the PILE subcommand to write the ASSEMBLE file onto 
disk. 

Since this assembler program uses OS Macros, you must issue the GLOBAL command to 
identify the CMS macro library, OSMACRO MACLIB, before you can invoke the assembler. 
The ASSEMBLE command invokes the VM/SP assembler to assemble the source file; the 
asterisks (*) indicate the CMS blip character, which you may or may not have made 
active for your virtual machine. 
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ASSEMBLER DONE 


0ST00230 23 LA R3,0 INITIALLY SET RETURN CODE 
IFO188 R3 IS AN UNDEFINED SYMBOL 

OST00240 24 OPEN (INDATA,OUTDATA, (OUTPUT) ) OPEN FILES 
4000000 27+ 12,*** IHBOO2 INVALID OPTION OPERAND SPECIFIED-OUTDATA 
IFO197 *** MNOTE *** 

OST00290 32 LA R3, 100 SET RETURN CODE 

IFO188 R3 IS AN UNDEFINED SYMBOL 

OST00340 37 LA R3, 200 SET RETURN CODE 

IFO188 R23 IS AN UNDEFINED SYMBOL 

OST00460 63 LR R15,R3 LOAD RETURN CODE 

IFO188 R3 IS AN UNDEFINED SYMBOL 

NUMBER OF STATEMENTS FLAGGED IN THIS ASSEMBLY = 5 


R (00012) ; 
edit ostest assemble 


locate /r2 
R2 EQU 2 
i r3 equ 3 
/open 
OPEN (INDATA,OUTDATA, (OUTPUT) ) OPEN FILES 
C /a/lar/ 
OPEN (INDATA,,OUIDATA, (OUTPUT) ) OPEN FILES 
file 
R; 


assemble ostest 


* 


ASSEMBLER DONE 
NO STATEMENTS FLAGGED IN THIS ASSEMBLY 


Rs 

filedef indd disk test data a 
R; 

filedef outdd punch 

R3 


#cCp spool punch to * 
load ostest 


The assembler displays errors encountered during assembly. Depending on how 
accurately you copied the frogram in this sample sesSion, you May or may not receive 
some of these messages; you may also have received additional messages. 
You must edit the file OSTEST ASSEMBLE and correct any errors in it. The errors 
placed in the example included a missing comma on the OPEN macro, and the omission 
of an EQU statement for a general register. These changes are made as shown. The 
CMS Editor accepts a diagonal (/) as a LOCATE subcommand. 
After all the changes have been made to the ASSEMBLE file, you can issue the FILE 
subcommand to replace the existing copy on disk, and then reassemble it. 
This time, the assembler completes without encountering any errors. If your 
ASSEMBLE file still has errors, you should use the editor to correct then. 
The FILEDEF command is used to define the input and output files used in this 
program. The ddnames INDD and OUTDD, defined in the DCBs in the program, must have a 
file definition in CMS. To execute this program, you should have a file on your 
A-disk name TEST DATA, which must have fixed-length, 80-character records. If you 
have no such file, you can make a copy of your ASSEMBLE file as follows: 

copyfile ostest assemble a test data a 
The output file is defined as a punch file, so that it will be written to your 
virtual card punch. 
The CP SPOOL command is issued, using the #CP function, to spool your virtual punch 
to your virtual card reader. When you use the #CP function, you do not receive a 
Ready message. 
The LOAD command loads the TEXT file produced by the assembly into virtual storage. 
The START command begins program execution. 
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R; 

start 

DMSLIO740I EXECUTION BEGINS... 

DMSSOPO36E OPEN ERROR CODE *O4 ON "OUTDD *. 
R (00200) ; 


filedef 
INDD DISK TEST DATA Al 
OUTDD PUNCH 


R; 

filedef outdd punch (lrecl 80 recfm f 

R; 

#cp query reader all 

NO RDR FILES 

load ostest (start 

DMSLIO740I EXECUTION BEGINS... 

PUN FILE 6198 TO BILBO COPY 01 NOHOLD 


Rs 

fi indd reader 

R; 

fi outdd disk new osfile a4 (recfm fb block 1600 lrecl 80 
R5 


listfile new osfile a4 (label 
DMSLSTOO2E FILE NOT FOUND. 

R (00028) ; 

run ostest 

EXECUTION BEGINS... 


* 
R; 

listfile new osfile a4& (label 

FILENAME FILETYPE FM FORMAT LRECL RECS BLOCKS DATE TIME LABEL 

NEW OSFILE AW F 1600 5 10 9/30/75 8:26:14 PAT198 

R; 

An open error iS encountered during program execution. The CMS ready message 


indicates a return code of 200, which is the value placed in it by your progran. 

The FILEDEF command, with no operands, results ina display of the current file 
definitions in effect. 

Error code 4 on an open request means that no RECFM or LRECL information is 
available. An examination of the program listing would reveal that the DCB for 
OUTDD does not contain any information about the file format; you must supply it on 
the FILEDEF command. Re-enter the FILEDEF command. 

You can use the CP QUERY command to determine whether there are any files in your 
card reader. It should be empty; if not, determine whether they might be files you 
need, and if so, read them into your virtual machine; otherwise, purge then. 

Use the LOAD command to execute the program again; this time, use the START option 
of the LOAD command to begin the program execution. 

The PUN FILE message indicates that a file has been transferred to your virtual card 
reader. The ready message indicates that your program executed successfully. 

For the next execution of this program, you are going to read the file back out of 
your card reader and create a new CMS disk file, in OS Simulated data set format. 
FI is an acceptable system truncation for the command name, FILEDEF. 

The LISTFILE command is issued to check that the file NEW OSFILE does not exist. 

The RUN command (which is an EXEC procedure) is used instead of the LOAD and START 
commands, to load and execute the program. The ready message indicates that the 
program completed execution. 

The LISTFILE command is issued again, andthe file NEW OSFILE is listed. (If you 
issue another CP QUERY READER command, you will also see that the file is no longer 
in your card reader.) 
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Sample Terminal Session for DOS Programmers 


The following terminal session shows how you might create an assembler language program 
in CMS, assemble it, correct assembler errors, and execute it. All the lines that appear 
in lowercase are lines that you should enter at the terminal. Uppercase data represents 
the system response that you should receive when you enter the command. 


The input data lines inthe example are aligned in the proper columns for the 
assembler; if you are using a typewriter terminal, you should set your terminal's tab 
stops at columns 10, 16, 31, 36, 41, and 46 and use the Tab key when you want to enter 
text in these columns. If you are using a display terminal, when you use a PF key or an 
input character defined as a tab, the line image is expanded as it is placed in the 
screen output area. 


Note: The assembler, in CMS, cannot read macros from VSE/AF libraries. This’ sample 
terminal session shows how to copy macros from VSE/AF libraries and create CMS MACLIB 
files. Ordinarily, the macros you need should already be available in a system MACLIB 
file. You do not have to create a MACLIB each time you want to assemble a progran. 


There are some errors in the terminal session, so that you can see how’ to correct 
errors in CMS. 
1 cp link dosres 130 130 rr linkdos 
DASD 130 LINKED R/O 
R; 
access 130 z 
Z (130) R/O - DOS 


R; 
Z set dos on 2 
R; 
3 edit dostest assemble 
NEW FILE: 
EDIT: 
input 
INPUT: 
begpgm csect 
balr 12,0 
using *,12 
la 13, savearea 
open infile,outfile 
loop get infile 
put outfile 
b loop 
eodad equ * 
close infile,outfile 
eo j 
eject 
buffer dc CL80* * 
infile dtfdi modname=shrmod,ioareal=buffer,devaddr=sysipt, 
4 
EDIT: 
1 Use the CP LINK command to link to the DOS system residence volume and the ACCESS 
command to access it. In this example, the system residence is at virtual address 
130 and is accessed as the Z-disk. 
2 Enter the CMS/DOS environment, specifying the mode letter at which the DOS/VS 
(VSE/AF) system residence is accessed. 
3 Use the EDIT command to create a file named DOSTEST ASSEMBLE. Since the file does 


not exist, the editor indicates that it is a new file and you can use the INPUT 
subcommand to enter input mode and begin entering the input lines. 

uf} Since the DTFDI macro statement takes up more than one line, you have to enter a 
continuation character in column 72. To do this, you can enter a null line to return 
to edit mode and execute the $MARK edit macro, which places an asterisk in column 
72. j%$If the $MARK edit macro is not on your system, you will have to enter a 
continuation character some other way. (See "Entering a Continuation Character in 
Column 72" in “Section 5. The Editors.") 
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$mark 
save#tinput 
EDIT: 
INPOT: 
eofaddr=eodad,recsize=80 
outfile dtfdi modname=shrnod,ioareal=buffer,devaddr=syspch, 


EDIT: 
$mark 
save#input 
EDIT: 
INPUTS: 
recsize=81 

shrnod dimod typefle=output 
endpgm equ * 

end 


edit getmacs eserv 

NEW FILE: 

EDIT: 

tabs 2 72 

input 

INPUT: 

punch open,close,get,put,dimod,dtfdi 


EDIT: 

file 

R; 

assgn sysipt a 
R5 

eserv getmacs 
R; 


Before continuing to enter input lines, the EDIT subcommand SAVE is issued to write 
what has already been written onto disk. The CP logical line end symbol  (#) 
separates the SAVE and INPUT subcommands. 

Another continuation character is needed. 

A null line returns you to edit mode. You may want, at this point, to proofread your 
input file before issuing the FILE subcommand to write the ASSEMBLE file on disk. 

To obtain the macros you need to assemble this file, use the editor to create an 
ESERV file. By setting the logical tabs at columns 2 and 72, you can _ protect 
yourself from entering data in column 1. 

PUNCH is an ESERV program control statement that copies and de-edits macros from 
source statement libraries; in this case, the system source statement library. The 
output is directed to the SYSPCH device, which the CMS/DOS ESERV EXEC assigns by 
default to your A-disk. 

You must assign the logical unit SYSIPT before you invoke the ESERV command. GETMAACS 
is the filename of the ESERV file containing the ESERV control statements. 
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listfile getmacs * 


GETMACS ESERV A1 
GETMACS MACRO Al 
GETMACS LISTING Al 
R; 

maclib gen dosmac getmacs 
Rs 

erase getmacs * 

R5 

global maclib dosmac 
R; 

assemble dostest 

* 

* 


ASSEMBLER DONE 

DOSO004O 4 LA 13,SAVEAREA 

ITFO188 SAVEAREA IS AN UNDEFINED SYMBOL 

DOS0O0110 35 EOJ 

IFOO78 UNDEFINED OP CODE 

NUMBER OF STATEMENTS FLAGGED IN THIS ASSEMBLY = 2 
R (00008); 

edit dotest assemble 


EDIT: 

locate /buffer/ 

BUFFER DC CL80* ? 
input savearea ds 9d 
file 

R; 


edit eoj eserv 
NEW FILE: 
EDIT: 

i punch eoj 
file 

R; 

listio sysipt 
SYSIPT DISK A 
R5 

eserv eoj 

R; 


After the ESERV EXEC completes execution, you have three files. You may want to 
examine the LISTING file to check the ESERV program listing. The MACRO file 
contains the punch (SYSPCH) output. 

The MACLIB command creates a macro library named DOSMAC MACLIB. Since the MACLIB 
command completed successfully, you can erase the files GETMACS ESERV, GETMACS 
LISTING, and GETMACS MACRO; an asterisk in the filetype field of the ERASE command 
indicates that all files with the filename of GETMACS should be erased. 

Before you can invoke the assembler, you have to identify the macro library that 
contains the macros; use the GLOBAL command, specifying DOSMAC MACLIB. 

The ASSEMBLE command invokes the VM/SP assembler to assemble the source file; the 
asterisks (*) indicate the CMS blip character, which you may or may not have made 
active for your virtual machine. 

The assembler displays errors encountered during assembly. ,Depending on how 
accurately you copied the program in this sample session, you may or may not receive 
some of these messages; you may also have received additional messages. 

To correct the first error, which was the omission of a DS statement for SAVEAREA, 
edit the file DOSTEST ASSEMBLE and insert the missing line. 

The second error indicates that the macro EOJ is not available, since it was not 
copied from the source statement library. Create another ESERV file to punch this 
macro. 

Use the LISTIO command to check that SYSIPT is still assigned to your A-disk, so 
that you do not have to issue the ASSGN command again. Then issue the ESERV command 
again, this time specifying the filename EOJ. 
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maclib add dosmac eoj 


R3 

Maclib map dosmac (tern 
MACRO INDEX SIZE 
OPEN 2 43 
CLOSE 46 43 
GET 90 56 
PUT 147 93 
DIMOD 241 647 
DTFDI 889 284 
EOJ 1174 6 
R; 

erase eoj * 

R; 

assemble dostest 

* 

x 

* 


ASSEMBLER DONE 

NO STATEMENTS FLAGGED IN THIS ASSEMBLY 
Rs 

listfile dostest * 

DOSTEST ASSEMBLE Al 

DOSTEST LISTING Al 


DOSTEST TEXT Al 
R; 

print dostest listing 
R; 


doslked dostest 


R; 

listfile dostest * 
DOSTEST ASSEMBLE Atl 
DOSTEST DOSLIB A1 


DOSTEST TEXT Al 
DOSTEST LISTING Atl 
DOSTEST MAP A5 
R; 


Use the ADD function of the MACLIIB command to add the macro EOJ to DOSMAC MACLIB. 
Then, issue the MACLIB command again, using the MAP function and the TERM option to 
display a list of the macros in the library. 

Erase the EOJ files. You should always remember to erase files that you do not need 
any longer. Reassemble the progran. 

This time, the assembler completes without encountering any errors. If your 
ASSEMBLE file still has errors, you should use the editor to correct then. 

Use the LISTFILE command to check for DOSTEST files. The assembler created the 
files, DOSTEST LISTING and DOSTEST TEXT. The TEXT file contains the object module. 
You can print the frogram listing, if you want a printed copy. Then, you may want to 
erase it. 

Use the DOSLKED command to link-edit the TEXT file into an executable phase and 
write it into a DOSLIB. Since this program has no external references, you do not 
need to add any linkage editor control statements. 

Now, you have a DOSTEST DOSLIB, containing the link-edited phase, and a MAP file, 
containing the linkage editor map. You can display the linkage editor map with the 
TYPE command, or use the PRINT command if you want a printed copy. 
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25 #cp spool punch to * 
punch test data a 

PUN FILE 0100 10 BILBO 
R; 

#cp query reader all 


COPY 01 NOHOLD 


ORIGINID FILE CLASS RECDS CPY HOLD DATE TIME 
PATTI 5840 A PUN 000097 01 NONE 09/729 15:00:39 

26 assgn sysSipt reader 
R; 
assgn syspch a 
R; 

27 dlbl outfile a cms punch output (syspch 
R; 
state punch output a 
DMSSTTOO2E FILE NOT FOUND. 

R (00028) ; 

28 global doslib dostest 
R5 
fetch dostest 
DMSFET710I PHASE "DOSTEST* ENTRY POINT AT LOCATION 
R; 

29 start 
DMSLIO74OI EXECUTION BEGINS... 

R; 

listfile punch output a (label 

FILENAME FILETYPE FM FORMAT LRECL RECS BLOCKS 
PUNCH OUTPUT Al F 80 97 10 
R; 

#cp query reader all 

NO RDR FILES 

25 To execute this program in CMS/DOS, punch a file 
records into your virtual card punch. If you 
fixed-length, 80-character records, you can creat 
CMS Editor, or by copying your ASSEMBLE source f 
follows: 

copyfile dostest assemble a test data a 
Use the CP SPOOL command to spool the punch to y 
the PUNCH command to punch the file. The PUN FIL 
is in your card reader. Use the CP QUERY command 
only file in your reader. 

26 Use the ASSGN command to assign SYSIPT to your 
A-disk. 

27 When you assign a logical unit to a disk mode, y 
identify the disk file to CMS. For this progran 
file named PUNCH OUTPUT. The STATE command ensur 
exist. If it does exist, rename it, or else use a 
DLBL command. 

28 Use the GLOBAL command to identify the DOSLIB, 
executable phases, then issue the FETCH command 
FETCH command loads the executable phase into st 
executed without the START option, a message is di 
location of the program loaded. 

29 The START command begins program execution. The 


your program completed successfully. You can check 
using the LISTFILE command to list the file PUNCH 
command, you can see that the file is no longer in 


Appendix 


NAME TYPE DIST 
TEST DATA BIN211 
020000. 

DATE TIME LABEL 
9/29/79 14:50:55 BBB191 


that has fixed-length 80-character 
do not have any files that’ have 
e a file named TEST DATA with the 
ile with the COPYFILE command, as 


our Own virtual machine, then use 
E message indicates that the file 
to check that it is the first, or 
card reader and SYSPCH to your 
ou must issue the DLBL command to 
execution, you are creating a CMS 
es that the file does not already 
nother filename or filetype on the 


search for 
Name. The 
command is 
entry point 


DOSTEST, you want to 
specifying the phase 
Orage. When the FETCH 
Splayed indicating the 


CMS ready message aAindicates that 

the input and output activity by 
OUTPUT. If you use the CP QUERY 
your virtual card reader. 
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assgn sysipt a 


R; 

dlbl infile a cms punch output (sSysipt 
R3 

assgn syspch punch 

R3 

fetch dostest (start 

DMSLIO7401I EXECUTION BEGINS... 


PUN FILE 5829 TO BILBO COPY 01 NOHOLD 

R; 

read punch2 output 

R5 

listfile punch2 output a (label 

FILENAME FILETYPE FM FORMAT LRECL RECS BLOCKS DATE TIME LABEL 
PUNCH2 OUTPUT Al F 80 97 10 9/29/75 14:50:59 BBB191 
R; 


If you want to execute this program again, you can assign SYSIPT and SYSPCH to 
different devices; in this example, the input disk file PUNCH OUTPUT is written to 
the virtual punch. You do not need to reissue the GLOBAL DOSLIB command; it remains 
in effect until you reissue it or IPL CMS again. 

This time, the program execution starts immediately, because the START option is 
specified on the FETCH command line. 

Again, the PUN FILE message indicates that a file has been received in your virtual 
card reader. You can use the CMS command READCARD to read it onto disk and assign it 
a filename and filetype, in this example, PUNCH2 OUTPUT. 
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Sample Terminal Session Using Access Method Services 


This sample terminal session shows you how to use access method services under CMS. You 
should have an understanding of VSAM and access method services before you use this 
terminal session. 

The terminal session uses a number of CMS files, which you may create during the 
course of the terminal session; or, you may prefer to create all of the files that you 
need beforehand. Within the sample terminal session, the file that you should create is 
displayed prior to the commands that use it. 


This terminal session is for both CMS OS VSAM programmers and CMS/DOS’ VSAM 
programmers; all the ASSGN commands and SYSxxx operands that apply when the CMS/DOS 
environment is active are shaded. If you have issued the command SET DOS ON, you must 
enter the shaded entries; if not, you must omit the shaded entries. 


Notes: 


1. This terminal session assumes that you have, to begin with, a read/write CMS A-disk. 
This is the only disk required. Additional disks used in this exercise are temporary 
disks, formatted with the Device Support Facility (DSF) program under CMS. If you 
have OS or DOS disks available, you should use them, and remember to supply the 
proper volume and virtual device address information, where appropriate. The number 
of cylinders available to users for temporary disk space varies among installations; 
if you cannot acquire ample disk space, see your system support personnel for 
assistance. 


2. Output listings created by AMSERV take up disk space, so if your A-disk does not 
have a lot of space on it, you may want to erase the LISTING files created after 
each AMSERV step. 


3. If any of the AMSERV commands that you execute during this sample terminal session 
issue a nonzero return code; for example: 


R (00012); 


You should edit the LISTING file to examine the access’ method services’ error 
messages. The publication VSE/VSAM Messages and Codes contains the return codes and 
reason codes issued by access method services. You should determine the cause of 
the error, examine the DLBL commands and AMSERV files you used, correct any errors, 


and retry the command. 


q #cp define t3330 200 10 
DASD 200 DEFINED 
#¥cp query virtual 200 
DASD 200 3330 (TEMP) R/W 10 CYL 


#¥cp define t3330 300 10 

DASD 300 DEFINED 

#cp query virtual 300 

DASD 300 3330 (TEMP) R/W 10 CYL 


#cp define t3330 400 10 
DASD 400 DEFINED 
#cp query virtual 400 


DASD 400 3330 (TEMP) R/W 10 CYL 
1 These commands define temporary 3330 mindisks at virtual addresses 200, 300, and 
400. 
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File: PUNCH DSF 


INIT UNIT(200) DEVTYP(3330) NVFY VOLID(222222) DVTOC(0,1,1) - 
MIMIC (MINI (10) ) 

INIT UNIT(300) DEVTYP (3330) NVFY VOLID (333333) DVTOC(0,1,1) - 
MIMIC (MINI (10)) 

INIT UNIT(400) DEVTYP (3330) NVFY VOLID (444444) DVTOC(0,1,1) - 
MIMIC (MINI (10)) 


File: DSF EXEC 


ETRACE OFF 

ECNTRL = &1 

ECOMMAND CP CLOSE READER 

SCOMMAND CP PURGE READER CLASS I 

SCOMMAND CP SPOOL PUNCH CONT TO * CLASS I 
ECOMMAND PUNCH IPL DSF S ( NOH 

&COMMAND PUNCH &CNTRL &FILENAME ( NOH 
ECOMMAND CP SPOOL PUNCH NOCONT CLOSE 
&COMMAND CP SPOOL READER CLASS I NOHOLD 
ECOMMAND CP IPL OOC CLEAR ATTN 


exec dsf punch 


NO FILES PURGED 
PUN FILE nnnn TO CAMPBEL COPY 001 NOHOLD 


ICKOOSE DEFINE INPUT DEVICE, REPLY "DDDD,CUU® or 'CONSOLE!® 
ENTER INPUT/COMMAND: 


This file contains control statements for the DSF program, which initializes disks 
for use by VSAM. These disks are labelled 222222, 333333, and 448444, 

This file contains the commands necessary to use the DSF program ina virtual 
machine. 

Execute the DSF EXEC, specifying that the DSF control statements contained in the 
file "PUNCH DSF" should be appended to the standalone DSF progran. 

These messages are issued by the DSF standalone progran. 
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2540, 00c 

2540,00C 

ICKOO6E DEFINE OUTPUT DEVICE, REPLY *DDDD,CUU" or ‘CONSOLE! 
ENTER INPUT/COMMAND: 


console 

CONSOLE 

ICKDSF - SA DEVICE SUPPORT FACILITIES 5.0 TIME20:26:00 03/09/82 
INIT UNIT(200) DEVTYP (3330) NVFY VOLID(222222) DVTOC(0,1,1) - 

MIMIC (MINI (10) ) 

ICKO0700I 200 BEING PROCESSED AS LOGICAL DEVICE = 3330 PHYSICAL 
ICKOO3D REPLY U TO ALTER VOLUME 200 CONTENTS, ELSE T 

ENTER INPUT/COMMANDs: 


u 

U 

ICKO01314I VTOC IS LOCATED AT CCHH=X'0000 0001 AND IS 1 TRACKS. 
ICKO0001I FUNCTION COMPLETED, HIGHEST CONDITION CODE WAS 0 


INIT UNIT (300) DEVTYP (3330) NVFY VOLID (333333) DVTOC(0,1,1) - 
MIMIC (MINI (10) ) 
ICK00700I 300 BEING PROCESSED AS LOGICAL DEVICE = 3330 PHYSICAL 


ICKO03D REPLY U TO ALTER VOLUME 300 CONTENTS, ELSE T 

ENTER INPUT/COMMAND: 

u 

U 

ICKO1314I VTOC IS LOCATED AT CCHH=X'0000 0001" AND IS 1 TRACKS. 
ICKO0001I FUNCTION COMPLETED, HIGHEST CONDITION CODE WAS 0 


INIT UNIT(400) DEVTYP (3330) NVFY VOLID(444444) DVTOC(0,1,1) - 
MIMIC (MINI (10)) 
ICK00700I 400 BEING PROCESSED AS LOGICAL DEVICE = 3330 PHYSICAL 


ICKO03D REPLY U TO ALTER VOLUME 400 CONTENTS, ELSE T 

ENTER INPUT/COMMAND: 

u 

U 

ICK01314I VTOC IS LOCATED AT CCHH=X'0000 Q001* AND IS 1 TRACKS. 
ICKOOO001I FUNCTION COMPLETED, HIGHEST CONDITION CODE WAS 0 


ICKDSF MAXIMUM STORAGE USED = 278968 BYTES (FIXED = 258120, DYNAMIC 


ICKOO002I ICKDSF PROCESSING COMPLETE. MAXIMUM CONDITION CODE WAS 0 


Since the DSF control statements reside in the virtual card 


indicate to DSF the device type and the address of your virtual reader. 
This response tells DSF to output all run time information to your virtual machine 


console. 


PAGE 1 
DEVICE = 3330-11 
DEVICE = 3330-11 
DEVICE = 3330-11 
= 020848) 
reader, you must 


This response gives DSF permission to proceed with the initialization of the disk. 
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#cp ipl cms parm autocr 
CMS VM/SP1.2.0 SL 000 
R; 


#cp link vseaf 350 350 rr pass=read 
DASD 350 LINKED R/O; R/W BY awd 
access 350 z 

DMSACC 7231 Zz (350) R/O ~ DOS 

R$ 

set 0s on 2 ( vsan 

R; 


access 200 b 

DMSACC723I B (200) R/YW - DOS 
R; 

access 300 c 

DMSACC723I C (300) RYW - DOS 
R; 

access 400 d 

DMSACC723I D (400) RYW - DOS 
R; 


query search 


PLC191 191 A R/W 
222222 200 B R/W - DOS 
333333 300 Cc R/W - DOS 
UBH444 4OO D R/W - DOS 
MNT190 190 S R/O 
MNT191 190 Y/S R/O 
VSERES 350 2 R/O - DOS 
R; 


You must re-IPL CMS after all DSF processing has completed. 


If you are a CMS/DOS user, you must access the VSE/AF 


SYSRES disk and issue the 'SET 


DOS ON fm (VSAM* command. If you have not previously linked to the VSE/AF SYSRES, 


you must use the CP LINK command before you issue 
method is to have the operator ATTACH the SYSRES 
Consult with your system programmer for the procedure 


ACCESS the three newly formatted disks as your E-, C-, 


You can issue the QUERY SEARCH command to verify 
currently have accessed. 
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File: MASTCAT AMSERV 
DEFINE MASTERCATALOG - 
( NAME (MASTCAT) - 
VOLUME (222222) - 
CYL (4) - 
UPDATEPW (GAZELLE) - 
FILE (IJSYSCT) ) DATA (CYL(1)) 


R3 | ae es 

dlbl ijsysct b dsn mastcat {syscat perm extent 
DMSDLB331R ENTER EXTENT SPECIFICATIONS: 

19 171 


Rs 


amserv mastcat 
R; 


File: CLUSTER AMSERV 
DEFINE CLUSTER ( NAME (BOOK.LIST ) - 

VOLUMES (222222) - 
TRACKS (20) - 
KEYS (14,0) - 
RECORDSIZE (120,132) ) - 
DATA (NAME (BOOK.LIST.DATA) ) - 
INDEX (NAME (BOOK.LIST.INDEX ) ) 


amserv cluster 

4221A ATTEMPT 1 OF 2. ENTER PASSWORD FOR JOB AMSERV FILE MASTCAT 
gazelle 

R; 


File: REPRO AMSERV 
REPRO INFILE (BFILE - 
ENV ( RECORDFORMAT(F) - 
BLOCKSIZE(120) - 
PDEV (3330) ) ) - 
OUTFILE (BOOK) 


The file MASTCAT AMSERV defines the VSAM master catalog that you are going to use 
and provides space for suballocated clusters. 

Identify the master catalog volume, and use the EXTENT option on the DLBL command so 
that you can enter the extents. For this extent, specify 171 tracks (9 cylinders) 
for the master catalog. Since 4 cylinders are specified in the AMSERV file, the 
remaining 5 cylinders will be used for suballocation by VSAM. 

You must enter a null line to indicate that you have finiShed entering extent 
information. 

Issue the AMSERV command, specifying the MASTCAT file. The ready message indicates 
that the master catalog is created. 

Define a suballocated cluster. This cluster is for a key-sequenced data set, named 
BOOK.LIST. 

No DLBL command is necessary when you define a_ suballocated cluster. Note that 
Since the password was not provided in the AMSERV file, access method services 
prompts you to enter the password of the catalog, which is defined as GAZELLE. 

Use the access method services REPRO command to copy a CMS data file into the 
cluster that you just defined. 
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20 


21 


22 


23 


24 


ayy 


assgn sys001 a 


Re 
copyfile test data a (recfm f lrecl 120 
R; 

sort test data a book file a 

DMSSRT604R ENTER SORT FIELDS: 

1°14 


R; | 
dlbl bfile a cms book file (sys001 


sgn sys002 b 


dlbl book b dsn book.list (vsam sys002 
R; 

amserv repro 

Rj 


File: SPACE AMSERV 
DEFINE SPACE - 
( FILE (SPACE) - 
TRACKS (57) - 
VOLUME (333333) ) 


assgn sys003 c 
R: 


dlbl space c (extent sys003 
DMSDLB331R ENTER EXTENT SPECIFICATIONS: 
19 57 


R; 

amserv space 

H221A ATTEMPT 1 OF 2. ENTER PASSWORD FOR JOB AMSERV FILE MASTCAT 
gazelle 

R; 


You must identify the ddnames for the input and output files for the REPRO function. 
BFILE is a CMS file, which must be a fixed-length, 120-character file, and it must 
be sorted alphamerically in columns 1 through 14 The COPYFILE command can copy any 
existing file that you have to the proper record format; the SORT command sorts the 
records on the proper fields. 

The output file is the VSAM cluster, so you must use the VSAM option on this DLBL 
command. 

Create an AMSERV file to define additional space for the master catalog on the 
volume labelled 333333. 

Again, use the EXTENT option on the DLBL command so that you can enter extent 
information, and a null line to indicate that you have finished entering extents. 
Issue the AMSERV command. Again, you are prompted to enter the password of the 
Master catalog. 
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File: UNIQUE AMSERV 
DEFINE CLUSTER - 
( NAME (UNIQUE.FILE) - 
UNIQUE) - 
DATA - 
( CYL (3) - 
FILE (KDATA) - 
RECORDSIZE (100 132) - 
KRYS(12,0) - 
VOLUMES (333333 )) - 
INDEX - 
( CYL (1) - 

FILE (KINDEX) - 
VOLUMES (333333) ) 
dlbl kdata c (extent sys003 
DMSDLB331R ENTER EXTENT SPECIFICATIONS: 

76 57 


DMSDLB331R ENTER EXTENT SPECIFICATIONS: 
76 76 


R$ 
amserv unique 
4221A ATTEMPT 1 OF 2. ENTER PASSWORD FOR JOB AMSERV FILE MASTCAT 
gazelle 
R; 
File: USERCAT AMSERV 
DEFINE USERCATALOG - 
( CYL (8) - 
FILE (IJSYSUC) - 
NAME (PRIVATE.CATALOG) - 
VOLUME (444444) - 
UPDATEPW (UNICORN) - 
ATTEMPTS (2) ) - 
DATA (CYL (3) ) - 
INDEX ( CYL (1) ) - 
CATALOG (MASTCAT/GAZELLE ) 


assgn sys006 d 

R; 

dlbl ijsysuc d dsn private.catalog (extent sys006 pern 
DMSDLB331R ENTER EXTENT SPECIFICATIONS: 

19 152 


R; 
amserv usercat 
* 


R; 


TAPE 181 ATTACHED 


This AMSERV file defines a unique cluster, with data and index components. 

You must enter DLBL commands and extent information for both the data and index 
components of the unique cluster. 

Next, define a private (user) catalog for the volume 444444. This catalog is named 
PRIVATE.CATALOG and has a password of UNICORN. Again, as in step 13, space is made 
available for sukallccation. 

When you define a user catalog that you are going to use as the job catalog for a 
terminal session, you should use the ddname IJSYSUC. 

You may want to try an EXPORT/IMPORT function, if you can obtain a scratch tape fron 
the operator. When the tape is attached to your virtual machine, you receive this 
message. 
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File: EXPORT AMSERV 
EXPORT BOOK.LIST - 
INFILE (BOOK) - 
OUTFILE (TEMP ENV (PDEV (2400) REWIND NOLABEL ) ) 
R; 
amserv export (tapout 181 
DMSAMS361R ENTER TAPE OUTPUT DDNAMES: 
temp 
R5 


Files IMPORT AMSERV 


IMPORT - 
CATALOG (PRIVATE.CATALOG/UNICORN) - 
INFILE (TEMP ENV (PDEV (2400) REWIND NOLABEL)) - 
OBJECTS (BOOK.LIST VOL (444444) ) 


amserv import (tapin 181 

DMSAMS361R ENTER TAPE INPUT DDNAMES: 
temp 

Rs 


The file that is being exported is the cluster BOOK.LIST created above. If you do 
not have‘access to a tape, you can export the file to your CMS A-disk. Remember to 
change the PDEV parameter to reflect the appropriate device type. 

You must reissue the DLBL for BOOK.LIST, because there is a job catalog in effect, 
and the file is cataloged in the master catalog. Use the CAT option to override the 
job catalog. 

There is no default tape value when you are using tapes with the AMSERV command. You 
must specify the TAPIN or TAPOUT option and indicate the virtual address of the 
tape. You are prompted to enter the ddname, which for this file is TEMP. 

The last AMSERV file imports the cluster BOOK.LIST to the user catalog, 
PRIVATE. CATALOG. 

Read the tape in as inrut. 
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¢ logical line delete symbol 7 


-BX format word 376 
-CM format word 378 
-CS format word 378 
-FO format word 379 
-IlL format word 379 
-IN format word 379 
-OF format word 381 
-SP format word 382 
e-TR format word 383 


&$ special variable 

resetting 303 

using to test arguments 302 
&* special variable 

resetting 303 


uSing to test for aksence cf arguments 
302 
&ARGS control statement, changing &D 


special variables with 299 


&EREGEMSG control statement, when tc use 
337 

EBEGPUNCH control statement, when tc use 
327 

&BEGSTACK control statement, when tc use 
318,321 


S&BEGTYPF control statement 
examples 109 
when to use 314 
S&CONTINJE control statement 
following label 105 
used with &SERROR contrcl statement 329 
&SCONTROL control statement 
controlling execution 
EXEC procedure 329 
examples 110 
SDATATYPE built-in function, 
arguments 301 
SEMSG control statement, examples 337 
&ERROR control statement 
examples 106 
provide error exit fcr CMS commands 329 
S&EXIT control statement 
examples 105 
passing return code to CMS 314 
&GLOBAL special variable, testing recursion 
level of C¥S EXEC 310 
&6GLOBALn special variable 
example 306 
passing arguments 
310 
&GOTO control statement 
examples 105 
transferring 
procedure 305 
&HEX control statement, examples 298 


Summary of CMS 


using tc test 


to nested procedures 


control in CMS EXEC 


Index 


&I1F control statement 

Maximum number allowed in nest 305 

testing variable symbols 304 
SINDEX special variable 103 

testing 301 

using to establish loof 301 
&LENGTH built-in function, using to 

arguments 301 

&LITERAL built-in function 

examples 309 

examples of substitution 297 
&LOOP control statement 

example 107 


test 


execution summary when &CONTROL ALL is 
in effect 340 
preparing loops in CMS EXEC procedure 


308 
&n special variakle, manipulating 300 
&PUNCH control statement 
punching jobs to CMS batch facility 260 
using to create file 327 
&READ control statement 
ARGS operand 103 
changing &n special variables 300 
examples 107 
reading CMS commands 312 
EREALFLAG special variable 
determining if console stack needs to Le 
cleared 322 
using to test console stack 320 
ERETCODE special variable 
example 106 
testing after CMS command execution 331 
using with &CMS EXIT control statement 
311 
&SKIP control statement 
examples 106 
transferring 
Frocedure 307 
SSPACE control statement, example 108 
&STACK control statement 
stacking CMS EXEC files with 323 
using in edit macros 341 
using to stack null line 321 
when to use, in edit macros 343 
&SUBSTR built-in function, 
309,324 
&TIME control statement, example 109 
ETRACE statement, in EXEC 2 111 
&ETYPE control statement 
displaying prompting 
EXEC procedure 312 
examples 102,108,109 
when to use 314 
&TYPEFLAG special variable, testing whether 
CMS EXEC is displaying data 316 
&1 through &30 
special variables 103 
Substitution in EXECs 102 


ccntrol in CMS FXEC 


examples 


messages in CMS 


! (exclamaticn point), controlling whether 


Index 44) 


it is displayed 28 


$, used as first character of filename for 
edit macros 341 
$COL edit macro 354 
$CONT EXEC 346-347 
$DUP edit macro, example 73 
$LISTIO EXEC file 183 
$MACROS edit macro 350 
$MARK edit macro 351 
used to enter continuation character 80 
S$MOVE edit macro, how to use 73 
$POINT edit macro 353 


* (asterisk) 
in CMS EDIT subcommands' 65 
in fileids on command lines 45 
in filemode field 54 
in LISTFILE command 39 
used to write comments in CMS 
procedure 335 
*COPY statement 
examples 159 
in CMS/DOS 191 


EXEC 


/* 
CMS batch facility control card, used to 
Signal end of job 255 
end-of-file indicator 
in AMSERV file 207 
in batch job 263 


// vecord, used as delimiter in MACLIBs 
161,194 

/ (diagonal), as delimiter on CMS EDIT 
subcommands 64 

7JOB control card, description 254 

/SET control card, description 255 

% (percent Symbol), setting CMS EXEC 


arguments to blanks 300 


subcommand 
usage 89 
usage, on display terminal 409 


usage, as argument for CaS EXEC 
procedure 335 
?EDIT message 65 
# logical line end symbol 7 
restriction on stacking in CMS EXEC 


procedure 318 


using to enter null line in input mode 
62 


using when setting program function (PF) 
keys 402 
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#CP function 7,18 
uSing in edit or input mode 85 
using on display terminals 401 


J 


@ logical character delete symbol 7 
using when setting program function (PF) 
keys 402 


(egual sign) 

entered in fileids on command lines 45 
entered in filemode field 54 
subcommand (see REUSE subcommand) 


" logical escape symbol 8 
used when setting program function (PF) 
keys 402 


A 
abnormal termination 
DLBL definitions 185 
ACCESS command 
accessing CMS disks 15 
response when you access VSAM disks 209 
used with OS disks 149 
access method services 
control statements, executing 206 
DOS/VSE, using in CMS/DOS 205 
executing in CMS, examples 230 
functions 
DEFINE CLUSTER 232 
DEFINE MASTERCATALOG 
DEFINE USERCATALOG 
DELETE 233 


(abend), effect on 


J 


215-216,224-225 
217,225 


EXPORT 233-234 
IMPORT 233-234 
REPRO 233-234 


OS/VS, restriction on using in CMS 206 
return codes 207 
Sample terminal session 
using in CMS 205 
uSing tape input/output 229 
in CMS/DOS 220-221 
access nethods 
DOS, supported in CMS 179 
OS, supported in CMS 150 
accessing 
directories of DOS/VSE libraries 188 
disks 15 
as read-only extensions 53 
in CMS batch virtual machine 257 
DOS disks 178 
file directories for CMS disks 57 


439-446 


nultiple access systems with DIAL 
command 26 
OS disks 149 
VSE/AF system residence volume 176 
ACTION, DOS/VSE linkage editor control a 
statement 199 


ADD operand 
of MACLIB command 


L 


usage 158 
usage in CMS/DOS 192 
adding 
members to macro library 
example 158 
example in CMS/DOS 192 
address 
stops 
setting 243 
to enter CP environment 24 
virtual 
calculating for 
program 238 
definition 12 
for unit record devices 117 
A-disk 51 
ADSTOP command, 
243 
ALIAS, OS linkage editor control statement, 
Supported by TXTLIB command 167 
ALL 


instructions in 


how to set address’ stops 


operand 
of SBEGSTACK control statement, when 
to use 318 
of &BEGTYPE control statement, when 
to use 314 


of &CONTROL control statement, using 
to debug CMS EXECS 338 
allocating 
space for VSAM files 
in CMS/DOS 218 
VSAM extents on OS disks and minidisks 
223 
ALTER subcommand 
global changes 71 
how to use 70 
altering 
characteristics of spool files 119 
characters in CMS file, with ALTER 
subcommand 70 
multiple occurrences 
file 71 
AMSERV 
command 
executing in EXEC procedure 235 
how to use 206 
files, examples 206 
filetype 206 
usage in CMS 47 
functions under CMS 231 
using to read tapes 230 
annotated, edit macro 348 
annotating, CMS EXEC procedure 335 
APL, using on display terminal 413 
appending, data to existing files, during 
program execution 155 
arguments 
in CMS EXEC procedure 
checking 301 
passing to nested EXECS 310 
testing with &$ and &* 302 
on RUN command, passing parameter list 
267 
on START command, parameter list 267 
ASM3705 filetype, usage in CMS 47 
ASSEMBLE 
command 
assembling OS programs 164 


211,227 


of character in 


97,103,299 


in CMS/DOS 196 
filetype 
usage in CMS 47 
used as input to assembler 164 
assembling 
OS programs in CMS 164 
programs, using CMS batch facility 263 
programs in CMS/DOS 196 
sample terminal session 433 
source files, from OS disks 164 
VSAM programs in CMS 205 
ASSGN command 
entering before program execution 201 
uSing to assign logical units. 181 
assigning 
filemode letters to disks 51 
logical units in CMS/DOS 
before program execution 201 
for VSAM catalogs 217 
to disk devices 183 
to virtual devices 183 
values to variable symbols, 
procedure 104 
assignment statement, examples 104 
attention interruption 
causing 22 
effect of mode setting 30 


in CMS EXEC 


automatic 
IPL 6 
save function of CMS Editor 63 
AUTOREAD operand of CMS SET command, 
display terminals 403 
auxiliary control files 287 
preferred 288 
auxiliary processing routine, receiving 


control during I/O operation 155 
AUXPROC option, of FILEDEF command 155 
AUXxxxx filetype 

auxiliary control files 287 
usage in CMS 47 


B 
backspace 
characters 

changing in file being edited 78 
deleted in user input area 413 
effect of image setting 78 
entering on display terminal 412 

batch 


facility (see CMS batch facility) 
jobs for CMS batch facility 253 
non-CMS users 262 
processing, in CMS 253 
batch jobs 
purging 259 
reordering 259 
restarting 259 
BDAM, access method, CMS support 150 
BEGIN command, to return to virtual machine 
environment 18 
beginning 
tracing 243 
virtual machine execution 19 
blanks 
as delimiters, 
64 


on CMS EDIT subcommands 


Index 449 


in character strings changed with CHANGE 
subcommand 69 
used on OVERLAY subcommand 70 
blip, characters, setting 28 
BLOCK option, of FILEDEF command 154 
BLP (see bypass label processing) 


books, from DOS/VSE source statement 
libraries, copying 185 
BOTTOM subcommand, moving current line 


pointer to end of file 66 
BPAM access method, CMS support 150 
branching in CMS EXEC procedure 
&GOTO control statement 305 
&SKIP control statement 307 
based on SIF control statement 305 
BREAK subcommand, setting progran 
breakpoints 239 
breakpoints, setting 239 
BSAM access method, CMS support’ 150 
buffers, used by FSCB 272 
BUFSP option 
of DLBL command 223 
in CMS/DOS 215 
bypass label processing, tapes 129 


C 
calculating storage 
virtual machine 202 
caller id, in tape label processing 130 
calling HELP files 358 
examples 359 
canceling 
changes made during CMS edit session 63 
DLBL definitions 185 
FILEDEF definitions 152 
verification of changes made 
Editor 69 
card punch 
used to send jobs 
254 
using in CMS EXEC procedure 326 
card reader 
restriction on use in 
facility 258 
spooling punch or printer files to 118 
cards 
used as input to CMS. batch 
253,262 
/* as end-of-file indicator 255 
CASE subcommand, usage 76 
CAT option of DLBL command 223 
identifying catalogs 226 
in CMS/DOS 215,217 
cataloged procedures, OS, equivalent in CMS 
148 
causing breaks in text 376 


available in your 


by CMS 


to CMS batch facility 


job for CMS batch 


facility 


CAW (channel address word), displaying, 
with DISPLAY command 246 
CHANGE 
command, changing hold status on spool 
files 120 
subcommand 


global changes 71 

how to use 69 

using in edit macros 346 
uSing on display terminal 409 
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changing 
characteristics of spool files 117 
characteristics of unit record devices 
117 
file identifier, on SAVE subcommand 85 
filemode numbers 56 
filemode of file, FMODE subcommand 35 
lines in file being edited 69 
that contain backspace characters 78 
multiple occurrences of character string 
in file 71 
changing output 
character 383 
changing the HELP facility 369 


representation of a 


channel address word (see CAW (channel 
address word)) 
channel status word (see CSW (channel 
status word) ) 
character, strings, changing 69 
characters 
altering 
with ALTER subcommand 70 
with CHANGE subcommand 69 
deleting from line 7 
special 
defining translate table for entering 
31 


displaying on display terminal 412 
entering on display terminal 412 
translated to uppercase, in edit macros 
341 
valid in CMS file identifiers 44 
CLASS, operand of SPOOL command 118 
classes 
CP command privilege 395 
of CP spool files 118 
clearing 
console stack 
at top or end of file 343 
for edit macro execution 343 
in CMS EXEC procedure 322 
issuing message after 343 
DLBL definitions 185 
FILEDEF definitions 152 
job catalogs 227 
job catalogs in CMS/DOS 218 
CLOSE macros, OS simulation 126 
closing 
CMS files, after reading or writing 275 
virtual card punch, after using &PUNCH 
control statement 326 
virtual unit record devices 278 
clusters, VSAM, defining and deleting 232 
CMS 
operand of DLBL command 184 
saved system name 250 
CMS (Conversational Monitor Systen) 
basic description 3 
commands (see CMS commands) 
file system 43 
file system commands, Samples 
files (see files, CMS) 
loading into your virtual machine 6 
OS simulation 147 
understanding it 1 
VSE/AF simulation 175 
CMS batch facility 
control cards 253 


417-425 


J 


/* 255 
/SJOB 254 
/SET 255 
controlling spool files 257 
description 253 
housekeeping done after 
256 
how jobs are processed 256 
jobs for non-CMS users 262 
using CMS EXEC procedure to submit jobs 
260 
CMS commands 
executing 
from programs 267 
in CMS EXEC procedure 329 
in edit macros 341 
general information 5 
nucleus-resident 59 
processing tape labels’ 136 
search order 58 
stacking in CMS EXEC procedure 318 
summary 387 
that execute in transient area 59 
used in CMS/DOS (see CMS/DOS commands) 
used with OS data sets 149 
using CMS EXEC procedure to modify 329 
valid in edit macros 341 
CMS EDIT subcommands 
delimiters 64 
summary 93-96 
CMS Editor 
environment 19 
format of 3270 display screen 406 
how to use 61 
invoking 61 
in CMS EXEC procedure 318 
line mode on display terminal 411 
sample terminal session 417-425 
using on display terminal 407 
CMS environment 18 
CMS EXEC 
built-in functions, summary 106 
command 
using in EXEC procedure 295 
when to use 98 
control statements, summary 
files 
changing record format 98 
differences between fixed-length and 
variable-length 314,321 
record format 98 
stacking 322 


executing job 


113-115 


filetype, for edit macros 341 
interpreter, how lines are processed 
340 


procedures 97 
building 295 
debugging 338 
executable statements 295 
nesting 310 
opening and closing CMS files 275 


setting program function (PF) keys 
402 

Submitting jobs to CMS batch facility 
260 


testing in CMS subset 338 
to execute DOS programs 203 
to execute DSF program 439-446 


to execute OS programs 172 
used by non-CMS users to submit batch 
jobs 262 
with same names as CMS commands 29 
processing errors 336 
special variables, summary 115 
CMS EXEC file 100 
format 100 
modifying 102 
sorting 101 
CMS files (see files) 
CMS macro instructions 
examples 276 
usage 270 
CMS menu, example 361 
CMS stacks, example 319 
CMS subset 
environment 
using 91 
using to test CMS EXEC procedure 338 
CMSAMS, saved system name 251 
CMS/DOS 
commands 
ASSGN- 181 
DOSLIB 199 
DOSLKED 197 


19,84 


DSERV 188 

entering 21 

ESERV 187 

FETCH 200 

LISTIO 182 

PSERV 187 

RSERV 186 

sample terminal session 433-438 
SSERV 186 


summary 177 
end-of-tape processing 139 
environment 21 

entering 175 
program development using 175 
relationship to CMS and to VSE/AF 175 


restrictions on executing OS programs 
179 
CMSDOS, saved system name 251 
CMS/DOS 


tape label processing 133 
terminology 175 


CMSLIB, ddname used to identify OS macro 
libraries 161 
CMSLIB MACLIB 161,194,270 


CMSSEG, saved system name 251 
CMSUT1 file, CMS commands that create 51 
CMSVSAM, saved system name 251 
CNTRL filetype 
control files 286 
usage in CMS 47 
command 
defaults 25 
environments 17 
how to enter 3 
language 3 
CMS 5 
CP 5 
lines, how scanned in CMS 266 
COMMENT statement 282 
comments 
in CMS EXEC procedure 335 
in HELP text files 378 
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communicating 
with CMS and CP during editing session 
84 
with VM/SP 3 
COMP 
operand of MACLIB command 
usage 160 


usage in CMS/DOS 193 
COMPARE command, comparing contents of CMS 
files 40 
comparing, variable symbols in CMS _ EXEC 
procedure 108,304 
compilers, supported in CMS 4 
components, of VM/SP 3 
compressing 
DOSLIB files 199 
MACLIBs 160 
in CMS/DOS_ 193 
CONCAT option, of FILEDEF command, example 
161 
conditional execution, 
Statement 307 
conditionally displaying text 378 
console 
log 
creating disk file from 405 
printing 405 
produced by CMS batch facility 259 
output, spooling for display terminal 
405 
console input buffer 
console stack 
cleared in case of error during edit 
Macro execution 342 
clearing 322 
clearing for edit macro execution 341 
exchanging data between programs 318 
using in CMS EXEC procedure 318 
using to write edit macros 343 
CONT 
operand of SPOOL command 117 
using to spool virtual punch in CMS 
EXEC procedure 326 
continuation character, how to enter in 
column 72 80 
continuous spooling 117 
control cards, for CMS batch facility (see 
CMS batch facility control cards) 
control file update, example 289 
controlling 
CMS loader 169 
execution of CMS EXEC procedure, summary 
of control statements 106 
converting 
decimal values to hexadecimal, in CMS 
EXEC procedure 296 
fixed-length files to variable-length 
format 75 
hexadecimal values to decimal, in CMS 
EXEC procedure 296 
CONWAIT function 
example 323 
using to clear console stack 323 
COPY 
files 
adding to MACLIB’ 158 
adding to MACLIB, in CMS/DOS_ 191 
filetype 


&LOOP control 


(see console stack) 
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usage in CMS 47 
usage in CMS/DOS 49 
function, on display terminals 399 
operand of SPOOL command 118 
COPYFILE command 
Changing filemode numbers 56 
changing record format of file 76 
copying files from one virtual disk to 
another 32 
creating small files from large one 90 
copying 
books from DOS/VSE 
libraries 186 
contents of display screen 399 
DOS files into CMS files’ 180 
files 
from one device to another 122 
from tape to disk 141 
lines in CMS file 73 
macros from DOS/VSE libraries to add to 
CMS MACLIB 191 
members of MACLIBs 
modules fron 
libraries 186 
OS data sets into CMS files 35 
parts of CMS file, with 
subcommand 73 
spool files 118 
VSAM data sets 233 
into CMS files 235 
copying modules from DOS library or SYSin 
tapes 180 
core image libraries 
CMS (see DOSLIB files) 
DOS/VSE, using in CMS/DOS 189 
corrections 
of lines as you enter them 6 
on a display terminal 401 
counters, using in CMS EXEC procedure 307 
CP (control program) 
basic description 3 
commands, general information 4 
privilege classes 395 
spooling facilities 117 
CP (control program) environment, entering 
18 
CP commands’ 19 
executing from programs 268 
Summary 396-400 
used for debugging 246 
compared with DEBUG subcommands 248 
using in CMS EXEC procedure 295 
uSing in job for CMS batch facility 258 
CP READ status, on display screen 403 
creating 
CMS EXEC file 98 
CMS files 
from DOS disks and tapes’ 181 
from DOS libraries 180 
from OS data sets’ 155,157 
in CMS EXEC procedure 323 
CMS macro libraries 
example 158 
example in CMS/DOS_ 191 
from DOS macro libraries 191 
DOSLIB files 199 
file system control block (FSCB) 270 
files with CMS Editor 61 


source statenent 


160, 193 


DOS/VSE relocatable 


GETFILE 


2 


HELP text files 375 
modules from DOS library or SYSIN tapes 
180 


one spool file from many files being 
printed or punched 118 

program modules’ 170 

programs, Sample terminal session 
429-432 


reserved filetypes 333 

user-written commands’ 171 

user-written edit macros 337 
creating buffers 

using the DESBUF command 318 

using the DROPBUF command 318 

using the MAKEBUF command 318 

using the SENTRIES command 318 
CSW (channel status word), displaying, with 
DISPLAY command 246 
current line pointer 

displaying when verification is off 86 

how to use 65 

position on display terminal screen 402 

positioning 68 

subcommands for display terminals 410 
cylinders 

extents 

entering in CMS/DOS 216 
specifying for OS disks 223 

on 2314/2319 disk 223 

on 3330 disk 223 

on 3340 Model 35 disk 223 

on 3340 Model 70 disk 223 


D 
data control block (DCB), 
FILEDEF command 151 
data sets, OS, using in CMS 149 
ddnames 
in OS VSAM prograns, restricted to seven 
characters in CMS 222 
specifying with FILEDEF command 151 
used by assembler 164 
used with assembler 196 
DDR command, used with OS data sets’) 149 
DDR program, dumping to tape 124 
DEBUG 
command 21 
to enter debug environment 238 
subcommands 
compared with CP debugging 
248 
entering 21 
monitoring program execution 239 
relationship to CP commands for 
debugging 246 
Summary 241 
debug environment 21 
debugging 
CMS EXEC procedure 336 
commands and subcommands used in 
relationship 246 
summary of differences 248 
nonrelocatable MODULE files 247 
programs 237 
summary of commands 37 
using CP commands 245 


relationship to 


commands 


decimal, and hexadecimal conversion in CMS 
EXEC procedure 298 
de-editing, DOS/VSE macros’ 187 
default 
command 25 
DLBL definition 184 
FILEDEF definition 152 
for filetypes for CMS Editor, 
establishing in CMS EXEC procedure 333 
logical line editing symbols 6 
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108 

listings from access method services 
207 


particular columns of file, 
edit session 69 
prompting messages in CMS EXEC procedure 
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how to use in CMS/DOS_ 183 
identifying VSAM data sets 222 
identifying VSAM data sets in CMS/DOS 
214 
relationship to ASSGN command _ 183 
specifying extents 228 
specifying extents in CMS/DOS 219 
DL/I programs in CMS/DOS_ 178 
DMS, prefixing error messages in CMS EXEC 
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DROPBUF command, used to create buffers 
318 
DSERV command, examples’ 188 
DSF (Device Support Facility) 213 
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files 112 
attributes 112 
format 112 
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command 
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first-in first-out stacking, in CMS’ EXEC 
procedure 320 


Index 457 


fixed-length, CMS EXEC files, difference 
between &STACK and &BEGSTACK 321 
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GLOBAL command 
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HELP command 
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DEBUG component 358 
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how to issue 358 
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HELP facility 
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commands 357 
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how it works 367 
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using the PF4 key 365 
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IJSYSCT 
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stacking in CMS EXEC procedure 320 
using in edit macros 345 
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CMS EXEC procedure 98 
System Product Editor 61 
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LABELDEF command 
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250 
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CMS/DOS environment 21 
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edit environment 63 
input mode 62 
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in CMS EXEC procedure 320 
in edit macros 343 
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pointer (see current line pointer) 
LINEDIT macro, executing CP commands 268 
LINEMODE subcommand, beginning line-number 
editing 82 
line-number editing 82 
Sample terminal session 426 
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LINK command 
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258 
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linkage conventions, for programs executing 
in CMS 265 
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edit macros, with $MACROS edit macro 
350 
information 


about CMS files 
about disks 40 
about DOS files 179 
about MACLIB members’ 158,193 
about OS and DOS disks 212 
about OS and DOS files 40 
about your terminal 38 
about your virtual machine 40 
logical unit assignments in CMS/DOS 182 
listing files 
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usage in CMS/DOS 49 
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loader 
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using 124 
tape file 
DCB address 131 
FCBSECT address 131 
tape files, in CMS 123 
tape handling, options 142 
tape label, processing, IBM standard 127 
tape label processing 
by CMS commands’) 136 
EOT 139 
EOV 139 
LABELDEF command 138 
MOVEFILE command 138 
under CMS/DOS' 133 
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tracing 
output, printing 244 
program execution 242 
controlling trace 244 
tracks 
entering extent information 
223 
humber per cylinder on disk devices 223 
TRANSFER command, moving reader files 120 
transferring 


line 


in terms of 


control in CMS EXEC procedure, using 
&GOTO control statement 305 
control in EXEC procedure, & ERROR 


control statement 329 
data files 35 
transient area 
CMS commands that execute in 59 
creating modules to execute in 269 
location in virtual storage 249 
restrictions on modules executing in 
269 
translate tables 
defining input and output characters for 
31 
using on display terminals 412 
translating, virtual storage to EBCDIC 245 
translating output characters 383 
transporting, VSAM data sets 233 
TRUNC 
option of COPYFILE command, 
convert record formats 75 


used to 


subcommand, setting right margin for 
input with editor 79 
truncating 
data while changing lines with editor 


79 
input data while using CMS Editor 79 
trailing blanks fron fixed-length 
records 75 
words in CMS EXEC procedure 295 
truncation, settings used by CMS Editor 79 
TSOMAC MACLIB 161,194 
TXTLIB 
conmand 
OS linkage editor 
Supported 166 
usage 166 
files 
assigning entry point names’ 166 
Manipulating 166 
filetype, usage in CMS 48 
members, assigning names for 166 
TYPE 
command, displaying CMS files 34 
subcomnand 


control statements 


Index 469 


effect on current line pointer 66 
using to restore screen display 409 
type call, in tape label processing 130 


U 

unassigning logical 

CMS/DOS_ 183 

underscore 
characters in file being edited 78 
using on OVERLAY subcommand 70 

unique clusters, defining 232 

unit record, devices 117 

unlabelled tapes, defining 134 


unit asSignments in 


unresolved references, how CMS loader 
resolves 168 
UPDATE 
control statement usage 281 
filetype 
creating update files 281 
usage in CMS 49 
updating 
CMS file directories 57 
source files 280 
UPDLOG filetype, usage in CMS 49 
UPDTxxxx filetype, usage in CMS 49 
UPSI 
byte, setting in CMS/DOS 203 
operand, of CMS SET command, example 
203 
user catalog 
VSAM 225 


in CHS/DOS 217 
user file directory 57 
user program area 249 
executing programs and CMS commands 269 
userid 
for your virtual machine 5 
of CMS batch virtual machine 253 
specifying for output spool files 118 
user-written 
commands, creating 170 
edit macros 348 
using CMS macros, examples 277 
using PF1, example 365 
using PF12, example 365 
using PF3, example 365 
using the XEDIT subcommand 362 


Vv 
variable symbols 
compound 296 
examples of substitution 296 
how scanned 296 
in CMS EXEC procedure 103 
comparing 108 
using as counters 307 
reading values from terminal 314 
stacking in edit macros 343 
variable-length EXEC files, considerations 
for writing edit macros 345 
VARS operand of &READ control 
313 
verification setting 
changing in edit macros 345 


statenent 


470 IBM VM/SP CMS User's Guide 


changing on display terminal 410 

columns used by CMS Editor 69 
VERIFY subcommand 

canceling editor displays 86 

how to use 69 

using in edit macros 345 
verifying, execution of edit macros 342 
virtual 

addresses 

for disks 12 
for unit record devices 117 

storage (see virtual storage) 
virtual addresses, tapes 123 
virtual disks (see also disks) 

definition 12 
virtual machines 

definition 3 

size 249 
Virtual Machine/System Product (VM/SP) 

basic description 3 

command summaries 387 

components 3 

environments’ 17 
virtual storage 

addresses, calculating 238 

CMS utilization 250 

displaying 245 

examining in debug environment 238 

how CMS uses 250 

increasing size 89 

overlaying during program execution 269 

requesting information about 41 


specifying locations for program 
execution 269 
used by editor, what to do when it is 


full 88 
VM READ status, on display screen 403 
VMFASM EXEC procedure 290 
VMFDOS command _ 180 
VM/SP (see Virtual Machine/System Product 
(VM/SP) 
VM/SP System Product Editor 
Product Editor) 
vn/370 online 5 
VOLID parameter, FILEDEF command 127 
VSAM 
access method, CMS support 150 
catalogs 
deleting 233 
passwords 227 
passwords in CMS/DOS 218 
using in CMS/DOS 215 
clusters 
defining 232 
deleting 233 
unique 232 
data sets, manipulating 
command 205 
files 
allocating space for 213 
identifying multivolume 228 
identifying multivolume in 
219 
relationship to CMS files 43 
input and output files 
defining 222 
defining in CMS/DOS 214 
master catalog 


(see System 


with AMSERV 


CMS/DOS 


J 


9 


defining 224 
defining in CMS/DOS 215 
identifying 224 
identifying before executing programs 
205 
identifying in CMS/DOS 215 
sharing 209 
multivolume extents 
specifying 228 
specifying in CMS/DOS 219 
option 
of DLBL command 222 
of DLBL command, in CMS/DOS 214 
programs, compiling and executing in CMS 
205 
user catalogs 
defining 225 
defining in CMS/DOS 217 
using in CMS 205 
VSAPL program, invoking on display terminal 
413 
VSE/AF 
differences between CMS/DOS 134 
tape label processing 134 
VSE/AF macro, summary 195 
VSE/AF system residence 
CMS/DOS 176 
VSE/AF TLBL card, in 
134 


volume, using in 


tape label processing 


W 
wait bit, in 
246 
WAITT macro, usage 278 
Warning messages, controlling whether you 
receive them 27 
writing 
CMS files 
in CMS EXEC procedure 323 
With FSWRITE macro 274 
CMS files onto disk, disk determination 


program new PSW, modifying 


54 

edit macros 341 

error messages in CMS EXEC procedure 
330 


labels on CMS disks’ 13 
lines to terminal 276 
specific records in CMS file 273 


writing CMS files onto disk, how the CMS 


Editor selects disk 63 
WRIERM macro, examples 278 
WVOL1 function, in tape processing 137 


DEBUG subcommand, example 240 
EDIT subcommand, usage 8/7 
XEDIT command, invoking the System Product 
Editor 61 
XEDIT LOCATE subcommand 362 


XEDIT subcommand, invoking 4,10, 362 


XY 
Y subcommand, usage _ 87 


Z 
ZAP filetype, usage in CMS 49 
zone setting 
columns used by CMS Editor 69 
increasing 79 
ZONE subcommand 


setting truncation columns for CHANGE 
subcommand 79 
specifying columns for CMS’ Editor to 
search 69 
1 
19E virtval disk address, accessed as 


Y-disk 51 

190 virtual disk address 
accessed as S-disk 51 
using to IPL CMS 6 


191 virtual disk address, accessed as 
A-disk 51 
192 virtual disk address, accessed as 
D-disk 51 


3 


3270 terminals (see display terminals) 


Index 471 


SC19-6210-1 


“+ 


IBM VM/SP: CMS User’s Guide (File No. S370 /4300-39) 


Printed in U. S. A. 


SC19-6210-1 


Staples can cause problems with automated mail sorting equipment. 


Note: 


Please use pressure sensitive or other gummed tape to seal this form. 


IBM VM/SP: READER’S 
CMS User’s Guide COMMENT 
SC19-6210-1 FORM 


This manual is part of a library that serves as a reference source for systems analysts, 
programmers, and operators of IBM systems. You may use this form to communicate your 
comments about this publication, its organization, or subject matter, with the understanding 
that IBM may use or distribute whatever information you supply in any way it believes 
appropriate without incurring any obligation to you. 


Your comments will be sent to the author’s department for whatever review and action, if 
any, are deemed appropriate. Comments may be written in your own language; English is 
not required. 


Note: Copies of IBM publications are not stocked at the location to which this form is 
addressed. Please direct any requests for copies of publications, or for assistance in using your 
IBM system, to your IBM representative or to the IBM branch office serving your locality. 


Yes No 
¢ Does the publication meet your needs? rT] CJ 
e Did you find the material: 
Easy to read and understand? T] T] 
Organized for convenient use? rT] CT 
Complete? TI TI 
Well illustrated? 1 CT 
Written for your technical level? CT T] 
e What is your occupation? 
¢ How do you use this publication: 
As an introduction to the subject? CT] As an instructor in class? CT] 
For advanced knowledge of the subject? r As a student in class? CT] 
To learn about operating procedures? rT] As a reference manual? CJ 


Your comments: 


If you would like a reply, please supply your name and address on the reverse side of this form. 


Thank you for your cooperation. No postage stamp necessary if mailed in the U.S.A. 
(Elsewhere, an IBM office or representative will be happy to forward your comments or 
you may mail directly to the address in the Edition Notice on the back of the title page.) 


SC19-6210-1 


Reader’s Comment Form 


Fold and Tape Please Do Not Staple 


BUSINESS REPLY MAIL 


FIRST CLASS PERMIT NO. 40 ARMONK, N.Y. 


Fold and Tape 


POSTAGE WILL BE PAID BY ADDRESSEE: 


International Business Machines Corporation 
Department G60 

P.O. Box 6 

Endicott, New York 13760 


If you would like a reply, please print: 


Your Name 

Company Name 
Street Address 
City 
State 

IBM Branch Office serving you 


Department 


Zip Code 


NO POSTAGE 
NECESSARY 


IF MAILED 
IN THE 
UNITED STATES 


‘VS ‘A Ul pelUlid 


aul} Budiy PIO" JOIND — — — — — — 


(6€-O0EV/OZLES “ON A!4) BPIND S 49ST SIND :dS/IWA WAl 


L-OLC9-6L9OS 


